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stay In Control Wherever You Go. 







For more than a decade, Timbuktu Pro and netOctopus 
have been the leading remote control, file transfer and 
systems administration applications for the Mac OS. 


Now, both of these indispensable tools 
are updated to take full advantage of the 
world’s most advanced operating system. 




Windows XP Ready 


Timbuktu Pro 

Whether you're at home or at work, Timbuktu Pro allows you to operate distant 
computers as if you were sitting in front of them, transfer files or folders quickly 
and easily, and communicate by instant message, text chat, or voice intercom. 

http; //www.timbuktupro.com 


netOctopus 

Intuitive and powerful, netOctopus can manage a network of ten or 10,000 
computers. Inventory computers, software and devices on your network; distribute 
software; configure remote computers; and create custom reports on the fly. 
http;//WWW. netOctopus.com 

Learn more, try it, or buy it online. Call us at 1-800-485*5741. 


timbuktu® * netOctopus® 
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YOUR DATABASE SERVER WITH THE 

C-TREE* SERVER SDK 



Today’s database demands are ol'len too complex I’or Lradilional database servers. 
Tlie functionality and precise level of control you need is simply not avoidable. 
Perhaps you need alternate sort criteria for your data or a special tvv^ist in the 
threading or communication logic. 

FairC'om’s c-tree'"’ Server SDK allows you to create a customized, 
industrial-strength server designed for your particular needs. Use 
FairCTmi's kerne), with t>vcr 20 years of proven stability, or override 
functionality within specific subsystems to implement your own 
subtleties. Move your applicalioiTs data I/O functions to the 
server-side to decrease network tratTie and increase 
peiformance! 

FairCom’s c-iree Server SDK is used by companies 
worldwide such as Software AG and Citibank*'; It’s 
integrated seamlessly into c-tree Plus and includes 
complete source code to the server mainline and all the 
interface subsystems to the c-tree Server. And 
best of all, once you’ve created your unique, 
customized server, it is easy to install and 
adminisLer: no DBA required! 


Enhance our server with your own 
custom server-side functionality 

Move functionality from the client-side to 
the server-side to reduce network traffic 
and increase perhsrmance 

Modify or replace entire server 
subsystems 

Complete source for the server 
[iiainlinc, key server 
subsystems, and client-side 

Flexible OEM licensing 


Visit www.fairaom.com/ep/nrit/Bdk today to take control of your server 1 
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SYBASE INTEGRATION TECHNOLOGIES. EVERYTHING WORl 


Adaptive 
Enterprise No^ 
Availsibie on | 
Mac OS X 10.3 j 
Panther 1 j 


F! L E M A 1C E R . P R O "^ 0 

SCALE TO NEW HEIGHTS 


Sybase is helping tpd#ts*^g 
leading companies achieve 'ij 

Information Liquidity; a highly 
profitable state where all of 
your mformation is transformed 
into real economic value 


Want to enhance the 


performance 
of FileMaker Pro on MAC OS X? 
The same database engine that 
runs Wall Street can help you do 
just that 


A5E 12.5 increases the reliability, 
availability and scalability of 
your FileMaker Pro application. 
It provides better data integrity, 
world-class security and the 
ability to handle thousands of 
transactions per minute. It1l 
also give your users the power 
of SQL queries. 


A FREE Developer's Edition 
download is available online 
at sybasexom/filemaker 




ASE 12.5 for MAC OS X is yet 
one more example of how 






















'•'f W 




BETTER WHEN EVERYTHING WORKS TOGETHER 


























A publication of XPUUWCORPORATION 



iJseJ^mmai Mtivifikjsfj Tedmok^^ ^ 


HowTo CommunicateWith Us 


In this elecironic age, the art t>f 
communicaiicm lias become l>orh easier 
and more complicated, [s it any surprise 
that we prefer c-maii? 

II you have any questioas, fee) free to call us 
at 805/494-9797 or fax us at 805/494-9798. 

If you would like a subscription or need 
customer service, feel free to conma 
Developer Depot Customer Service at 
877‘MAC1*HCH 


DEPAimVlENn^S 

Orders, Clrcuhition, & Costonier Service 
Press Releases 
Ad Saks 
Editorial 

Prograj inner’s Cliallenge 

Ofiliiic Support 

Aecountiiig 

Mariredtig 

General 

SHe (artkles., into, I IRLs and luore^O 


c ust_seiv ice® mactech. com 
press_n:leases®mactcch .com 
atLsiile^®maaecii .com 
eciuorial®inactech .com 
pfqg_challerige® mactech .can 
onliiic^macterh .com 
^KXx)uiuing@niactcc’h.com 
iTiarketing@mactech.com 
inl'o@[iiactec li xtim 
httpv/www.macic'chxom 


The MacTeeb EdUorint Staff 
Publisher • Neil Tickiin 
Editor-m-Cliief • Dave Murk 
Managing Editor • les.sira Stubbiefield 
He^utur i'olummiHin 
Getting Started 
by Dave Mark 
QuickTime I'ooLKit 
by Tim Mt^nnx' 

Mac OS X Programming Secrets 
by Sc'on Kuustcr 
Kevicws/Kootrools 
by Micliael R. Ifarvc'y 
Patch Pane! 

by jolrn G Wclcli 
Section 7 
by Rich Morin 
Untangling the Web 
by Kevin I lemenwuy 
John and Pais’ Pu/:Kle Page 
by )t)bn Vink 

Hiff^aiar 0 *ntrihutarx 

Vicki Brown, Erick IVtkow^ski, 
l^iul E. Sevinv 

Maclecb's ikmrd of Advixorx 
Jordan IX^ii Mattson, Jim Straus 
and Jon Wic^Icrspun 


MacTcch’s Gontrihuting Editors 

• Midiucl Brian Bentley 

• Vicki Brown 

• Marshall Clow 

• John. C. IXuib 

• Ibni Djajudiningnii 

• Ihll DtxTrfekl, BlueworkI 

• Andrew S. f>o\vns 

• Richard V. Ford. Packeteer 

• Gordon Garb, Sun 

• llene 1 lolTman 

• Chris Kiilxmrn, Digital Forest 

• Rich Morin 

• John OTallon, Mnxum Dcvclopincnt 
- Will Porter 

• Avi Ra]i|X>poi1, Search Ttwils tamsulting 

• ’I’y Shipman, Kagi 

• Chuck Shouon. BlAP Systems 

• Qil Simone, Main Event Sfiftware 

• Steve Sisak, CfxJevvell Corporation 

• Chuck Von Raspy di. Plaid works 


Xpfain Corlmration Staff 
Chief Executive Officer • Neil Ticktin 
President • Antlrea J, Snidermun 
Controller • Michael Friedman 
Production Manager • Je,ssicu Stubblefield 
Production/Layout • Dunyl Smart 
Marketing Man:^cr * Nick IX'MclIo 
Account Executive • Larin Rivers 
atLsale,s®niac!ecii.ct>nt • 800-5-MACDEV 

Events Manager • Susan M. Worley 
internaUonal ■ Rose Kenijis 
Network Administrator • David Breffitt 
Accounting * Jan Weblier. Marcie Moriarty 
Castomcr Relations • Lium Line, Susan Poniranlx 
Shipping/Keceiving • Jtx-l lJ<iirdie 

Board of Advisors * Steven Gdler, Blake Hark, 
and Alan Camrud 


Ail ct inients ;ia' Ojpyrigiil 198^1 2003 Xptiin t>)rptjraii{>n. 
All righi.s MiuTcdi and IX-vt-kjix^ aie 

rcj^isieAd initbiiai-ks d X]^bin O irixiraiiun RadGatL GstTuI 
Gilts anti Gadgets, Xplain, iXMXpot. Ueptjt, llit^ OeptJt, 
OqxJl StoTC. Vitleo IXptX, Mmie Dept, Palni Game 
IX'p)!, Flashlighl IX^vit, Hspluin It MacDevd. nilNK 
Kdeteixv. Neil^itjfesikmal. NvtPniljve. JasaTech. WdVRdi, 
BcTtxii, UnitxTcch, Mir'fbth CXmtnil and the MaCtinofMm 
are ljudemarks or senke marks d Xjilain Gcwptjmtion. 
Spnxko is a ivgL'ai.Tied aackmark of fSprtdtrf Ckirpotatifxi. 
OtlKT trademuiks aid ai|))7i|?iiLs appearii^g in this priming or 
stifiwm* rx'rtjain rlx' pfopiTt)^ d ihcir lespctiive h jitiers. 


MacTecti Magazine (ISSN: 1067-8360 / USPS: 010227) Ls published monthiy by Xplain Corporation, 850-P I lampsliire Raid, W^alake Vilbige, CA 91361- 
28IX). Vok:e: 805/494-9797, FAX: 805/494-9798, Domestic subscription rates are $47.00 per ysir, Gmadian sulmTiprioas are $59.00 per year. All txher 
inicmitioruil suhscriptions am $97,00 per yeiir Domestic sottixe ctxle disk .subscriptions are $77 per year. All international disk subscriptions ate $97,00 a year. 
Please remit in IJ.S. funds only. PeiifxJical postage Ls paid at *rhou.sand Oalcs, CA and at additioruil mailing tjlfice. 

POSTMASlTiR Send address changes to MacTech Magazine. RO. Box 5200, Westlake Village, CA 91359-5200. 


'rill- siAFi^ 


MacTec:h • Dko^viblr 2003 






















C . g . n . t . e . n . t . s 

December 2003 • Volume 19, Issue 12 


QuickTime Toolkit 

44 The Matrix Revolutions 

Hondting Movie Fite Operations with Revofution 

By Tim Monroe 


t Cover Story 

52 1 Writing Cocoa Applications 
in Java 

By Steve Klingsporn 


Starting a Business 

75 Pursuing the Dream 

From Dream fo Reality 

By Chris Kilbourn 

Casting your .NET 

16 Compiling, disassembling and 
re-assembling .NET binaries 

Exploring .NET development on Mac OS X 

By Andrew Troelsen, Minneapolis, Minnesota 

Software Marketing 

70 Driving Traffic to Your Web Site 

Online Publicity for Your Software 

By Dave Wooldridge 

Patch Panel 

66 New Networking Tricks in Panther 

A quick look at some new tricks, good and bad, in Panther 
By John C Welch 


Getting Started 

6 Meet Andrew Welch 

By Dave Mark, Editor In Chief 


Java 

62 RemoteScriptRunner: Remotely execute 
scripts from any web browser 

By Joe Zobkiw 

Cocoa 

26 A simple debugging tool for Cocoa 

Another weapon in the fight against hugs 

By Sfeve Cehrmon 

Section 7 

42 ESR, etc. 

A multiplex review of a singular individuaL 

By Rich Morin 


Mac os X 

Programming 

Secrets 

Checking Out Kiosk 
Mode Features 

By Scott Knoster 


Untangling the Web 

55 Panther Roars, Database Meows 

Pandjer worth your time? Databases besides Hlemaker? Pffffttt 

By Kevin Hemenway, Titillating Entertainer 


DnciiMUUR 2003 • MAcTEcn 


I’ABLE or CON'Il'N't'S 


5 













GETTING 

STARTED 


Copyright 2003 hy Daw Mark 


Meet Andrew Welch 


This month's column is a l7ii of a departure from our normal 
Mac dev exploralion. As It^n^-dine renders know, 1 am a big 
gaming fan. I recently had the chince to hook up with one of 
the originators of shareware gaming on ihe Mac and I wanted to 
siiare this conversation with you. 

Andrew Welch, aka Ambrosia Software, Inc's el Presidente, 
started developing software in high sctiool because frankly, it 
was Ixinier tlian Oifjfjing l>urgLTs (lliougli he did have a stint as 
drive-thai guy at Roy Rogers). lie went on lo study 
l^hoTojournali.sin in college, but decided to pursue software 
development for a living rather tlian cany someone else’s 
chimera bags. He currently lives in Rexhester, NY, and has the 
(Kldly polar hc>bi>ies of origami and weight lifting. 

Dave: Can J call you Andrewv, or w^juld you prefer cl 
Presidente? 

Andrew: If you call me \d Pre.sidente” f might end up the 
target of some sort of “regime change", so let's keep it safe; 
"Andrew" is fine. 

Dave; I first became aware of Amlirosia in 1992 with the 
release of Maelstrom. Can yon give me a l^it of history here? 
What led up to MacLstroni? 

Andrew: 1 was actually in college at the time, working on 
a degree in Photojournalistii. Maelstruiii wa.s develof>ed 
over the summer, primarily because I heard someone state 
I hat good color animation wa.sn'r possible on the 
technologic iom de force at the time, a Mac llsi. 

It serened as a fun little project for me to hone my 68K asm 
('cxling skills; almost all of Maelstrom is written in assembler, 
with a few^ non-cntical inierfuce ruuiine.s done in C. I wrote 
the game myself, but 1 had a numlx-r of [X^ople wIkj assisted 
me, creating the graphics for the game, and all of my friends 
j:)iiched in play lesling it and hel()ing me record sound 
effects for it. 

1 polished it up, put it online on AOL, and was surpri.sed at 
flow popular il bccajne. 



ihc atkmtion to detaif in the 
graj)hu:s, 7he first game I rememher teitb truly sbarj) 30 
rendering and (KTfectly smtxdb mownient. 


— 

The Game. 

^ -- 

Vav jf# f luE.ili' * rk«l! ttid « h*F‘d luck en |{«u. 

Tb« Good 

The Bad 


Vow »(|ui|ip«d vWh pl^rn# 

flMBanv 4iid # f*ret jhitid. j 


An ^tereld. Tbrse suekers yet 
in the vey; fbeal 'em. 

I 

An ACHE supply csuixtvr; pick | 

Uk*s« up by running Ihun «v*r . | 


A steal ertereid. V* vn't blew 
'em 19 , but you chi meve 'em. 

\ 

A cbfMtiidf ififtinrt-fihpol this to 
ftl naorr bsnus petals. 

If- 

VhVA th»* JEtM-E y« MV4, tb* 
expleslen Is de¥*Et«tfity . 

0 

If peu sheet Itaise multlplfrrs, 
they iMilHply your b«fius peinti. 

# 

A !Th**ieki eMtoflemtamiS mtar. 

These yuy s ere extremely nesty. 


A EtreHled herder petrel reeve 
pilflt^ run 'em C'VM- te seve bin. 

* - 

yet iwked tnte enr «f 
these Vertexes, yeu'll regret It. 

ACMt Stif VHiiitrr# C4nt*1«: 

0 * ^<#14 pevtr, >, j 

I V Ifliaf skots, sh«ti, 

• 9 mKhtn* 9 ua «r luck. 

:5» 

A aivefiskl neef ship. Hot muiy 
live tv lell ebevt seeing 'em. 


Ikreir HC rMfiH far lit* aereeit, siyy etker key te exti... 


Ihe good and the bad guys. 

Dave: What was the state of shareware back then? Was there 
any kind of move me nt to organize shareware? Did you get 


Dave Mark is a longtime Mac' develo|xr and author and has written a tuimber of bexiks on Macinrosli development, including Leam C on the 
Mudnloshy Leam C++ on the Macintosh, and The Maemtosh Programming Primer scries. Be sure to check oiu Dave's wel) site at 
http://www.spic!erworksxoEii. 
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a lot of payments, as ct>mparcd Lo ihe number of game 
downloads? Where did people gel most shareware? 
CompuServe? AO!? 

Andrew: At the time, at least in my world, AOL and 
CompuServe were the major places to put softwaie. I'he 
web hadn’t taken off yel, and the Interner was something 
that cMily people with few scKial skills nuiUertxl about 
Shareware back tiien w^as fairly unorganized, in the sense 
that tliere were few protlucis that required license ccxles to 
operate, payment was optional, and you had to send in 
checks or cash to j^ay for something. One of my favorite 
tilings was receiving money in various currencies I’d never 
seen l)efore, frtjin all over the world, 

'lliere was stiimetliing disunctly cool about writing scjmething 
in my dorm RK)m in Upstate New York, and having people 
all over the world writing io me Alxmi it. 

As for payments received vs. downloads, it s never a meiric 
Tve considered imptmant. Many people download 
something, then forget alxmi it, trash it, or whatever. 1 
really didn*t pay too much anention to the money it was 
making, fx^nuise I was busy in college, doing things college 
kids do. 

Dave: 1992 saw the introtlitaion of System 7.1, as well as 
tlie Mac LC 11, tlie Quadra 9S0, the 2^ Mhz 68030-based 
FowerBook [4% the Mac 11 vx and Mac livi, arid the 


FowerBook Duo 210 and 250. Microsoft introduced 
Windows 3-1 and NeXT released NeXrSTFF 5-0 and 
NeXTSTCP 486. What was your dev environment hack then? 

Andixrwr I actually had the original NeXl' dtxiimentation, 
toO“ i was a NeXT developer, even though t actually didn’t 
own a machine (1 couldn’t afford one). On the Mac, iny 
development environment was origimilly 11IINK Pascal, but 
I transitioned to using 1111NK C (this is beh)re Symantec 
l>oughi them out). My main development machine was a 
Mac ILsi at the time, with a whopping (for the time!) I7mb 
of RAM! 

I actually started coding originally on a 512K "Fat Mac” - 
yes, youngims, this was the technology of the day* and it 
had only 312K of memory, f used a 12(X)baud mcxlem, and 
my life changed utterly when 1 was alrle to buy a 20mb 
hard drive for the machine. Prior to that, I Ixxjted frotii a 
1(K)K tloppy drive* and did all of my development on an 
external 4(>0K floppy disk. 

You young whipper-snappers have no idea how g<K)d you 
have it! God, I feel old now... 

AnyT\^ay, back to the question at hand. TTllNK C was a very 
cool development envirt.mmetit for the time* though it 
wasnl as friendly as THINK Pa.sc-il, the environment I 
suirted our piogratiiiiiing witli. I taught myself Ixjih 
languages, and the ‘’hible" at tlie time %vas a plione4x)ok 
style volume called Haside Macintosh." It was mo.stly an 
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exercise in curiosiry for me; 1 wanted to figure out how these 
computers worked, and 1 truly enjoyed creating things. 

Dave: More tlian ten years after Maelstrom, how has your 
development environment changed? 

Andrew: For my f:>ersonal development these days, I use 
Project Btiilder, It used to be Code Warrior, but to do some 
of the projects fve needed to do for Mac OS X, Project 
Builder was a belter, if less refined, choice. But now it isn't 
just me; we also liave an ace coder named Matt Slot 
working for us (we iiffeaioniiteiy call him our “Code 
Whore"), as well as developers all over die world we 
partner willi. 

i doiVt do as much coding as I used to. 1 do some work on 
our supporting libraries, and there are some major piojeets 
that dVQ all mine (such as ^ndpz Pro X), but 1 spent a lot of 
time rumiing the company and managing projects these days, 
fve dabbled a bit with Cocoa, such as our tree WireTap 
product for recording sy.stem audio, but fm not 
comfortable enough with it to .say I’m any gcK>d at it. I 
wish that I had the time to invesl to dive into ii deeper, but 
so it goes... 

Other tilings have changed a !iit. The development c 7 cie is 
no longer code, run, crash, poke around in MacsBug, then 
leixjot your computer while you .slam your head into the 
monitor. Lulier, rinse, refieat. In that sense, my sanity is 
signifiamtly improved these days. 

Dave: You u.setl to do all of your development in house, 
llou' ha.s this changed? 

Andrew: We try to stay very involved in the design and 
development of all of the products we w'ork on, because we 
collectively liave a kii of experience in terms of making a 
polished product that people will be inierestetl in. We are 
involved on many levels: helping to design the feature 
set/gamc play, offering icclinical assistance in the fomi of 
libraries weVe written that do very useful (and hart!) things, 
as well as debugging support, and then of course things 
publishers do, .such as marketing, .su[)[K>n, etc. 

We do Ixjth indiuuse and external beta testing, phased in 
so that it fits with where the program is in terms of 
development, and we manage the beta tests. External 
testing is a must, because there is no other w'ay you can 
get an idea how your product will perform in the wild. If 
I had a dollar for every time something 1 wrote crashed 
on someone else's machine, l)ui "worked for me", I’d be 
rich indeed. 

Dave: Clearly, games are one area where yt}u regally [Veed 
to be able to imive pixels quickly. Can you talk about the 
kinds of approaches it) blitting you use in house? Mow 
alxHil outside develtipers that you work with? 


Andrew: We used to do all sorts of very tricky things to blit 
pixels to the screen quickly, such as using custom assembler 
for critical portions. Now it’s mostly just of liistorical interest. 
Computers are Eisi enough now tliat you can safely just use 
the provided C^S routines such as CopyBitsO or even belter, 
jus! u.se OpenGh (for ix)lh 3f) and 2D). 

Dave; How has your net gatiiing strategy evolved over the 
years? Is there a .standard pnoicx'ol for finding op[x>ncnLs over 
t he net, for cxamf)le? Do you r<A\ your own net gaming libs? 

Andrew: Obvitiusly, net gaming is important, and has been 
for years. It's important to the point of designing your game 
around the physical limitatioas that things such as latency 
introduce, a.s well as designing your game to be a fun 
multiplayer game. 

We l(x>ked at availaide solutions out there, and decided to 
roll our own. We use something Matt Slot wrote called 
Network_Tool (hey, no one said liis forte was coming up 
with creative names), which handles TCiVIP as well as 
LIDP networking. It performs quite well, using proprietary 
algorithms of concatenating and retrying transactions. 
1 his is an example of a lilirary we develop and provide for 
the partners we work with to use. It takes care of the 
dirty, tough to write stuff, so people can gel on with 
making their game. 

.Similarly, we liave a library called Reggie that handles 
allowing |X*ople to find others on the net . It works in a very 
general manner, allowing for data to be stored in any format 
the client application wants, and iVs all stored on the back 
end in an SQL datal>ase. 

Dave: 1 know you recently implemented your own order 
processing system, I low did you used to do fulfill ment? 
How does the new .system work? Is it .something you 
wrote yourself^ 

Andrew: We have long had our own merchant account for 
cTcdit card processing, hut we decided it was long overdue 
that we lake it to the next level and automate and enhance 
our order processing system. We aime up with a set of 
design specs, and handed them off to a third party 
developer to implement them. 

Alas, in the end, we had to do (piite a bit of work ourselves 
to make it work the way we w^anted it to. On the upside, 
though, our cu.stomers get their license codes instantly, they 
can gel losl/renewed license codes sent to liiem any tiine 
they wish, and it all inlegrales seamlessly with our 
FileMaker Pro Server back end. 

Dave: What are the lechnical details Ix^hind your web sire? 
Do you use a DBMS? Is it straight IITML? Do you update it 
liy hand'' FIT? Use a management package? RRF.Llit? 
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Andrew: Our web site is for the mosi part fuelling kk) 
exciting. We have a number of custom written or modified 
Perl scripts that handle the drudgery of most of it. We set 
up systems so we generally don't have to edit HTML, just 
work witli custom scripts we’ve written to do various 
things to it, 

We update it by hand over sfip, and BBEdit is of course tlie 
l(K>l of choice to do any kind of serious editing. It’s true, it 
really doesn’t suck. 

Dave: You’ve got some fascinating utilities that have pushed 
the envelope beyond traditional application development. 
Snapz Pro is a perfect example. Can you take us i^ehind the 
curtain on some t)f this Lc-chnology, idl us a lat alxiuL how 
they work? 

Andrew': Snapz Pro X is ,st)mcliiing Tve bcxru working on 
heavily lately, WeVe done a major interface reorganization, 
and an even more major Inoost in performance of the video 
capture engine. When 2.0 is released, w'c’ll liave made 
video capture as easy to do as static screen captures 
(something Snapz Pro X excels at already), and I’m betting 
that many people will opt to put a short video (if their 
product in action up on tlieir web site to show it off, rather 
than a static screen shot. 

Making something like Snapz Pro X work involved very’ 
long se.ssions pnabing the various MatOS X system 
frameworks with tim (a command line tool) to ferret out the 
functionality we needed. Many the APIs we needed 
didn’t exist, and wailing for Apple to make iheiri available 
just wasii t a viable option. Remember folks, it's software - 
anything is possible, it just depends on how much effort 
you're willing to go through to make it liapptm. 

Dave; What advice w^jiild you give today’s shareware 
developers? 

Andrew: My nuiin piece of advice is not to set the bar low 
just because they are writing shareware, or they are pricing 
it cheaper tlian commercial counterparts. People tend to 
judge tilings by w'hy they offer them, not by how 
inexpensive they are. For instance, let's take games. 
Games are entertainment. If you go to the video store 
looking for a movie, you clon’t liypass the !letter movies for 
a budget $2 college film. Sure, it's cheaper, liut ii doesn't 
aiatlLT, you want U> lx.* entertained, 

Donf kid yourself that you can offer an inferior prcKluct ju.st 
because it is cheaper, and expect it to do well. 

My Ollier main piece of advice would be to figure out 
what you want to do. Many people who go into think 
they want to do the whole shebang: development, 
testing, marketing, support, carder processing, eit\, ele. 
This is a quick way to lose your sanity if what you really 
want to do is ju.st develop cool software. Figure out 


what you really want U> do, and partner with someone if 
it is appropriate. 

Dave: One of my lavorite things a!K)yi iKMng part of the 
Macintosh developer community is what an incredibly small 
world we live in. Whenever I travel 1 always seem to run 
into someone T know from ifiis universe. Don’t you have a 
story - sometliing abotit i>eer? 

Andrew: I recently went to Germany for Oktoberfest, 
which is a wild time, with some great German beers in 
mugs you need two hands to lift up, While sitting in an 
old brew house having some beers with friends, I was a 
little sur]>riscd to see a guy walking by with a Metrowerks 
t-shirt on. 

So 1 pulled him aside, and decided to clink mugs with him, 
and see what he used CodeWarrior for. As it turned out, he 
was a Metrowerks employee.., and all 20 or so people at his 
table were as well. So if the next version of CodeWarrior is 
a [)it delayed, I think we may know why.., tile coders are 
all off Ixxizing it up somewliere, 

Dave: What's on the horizon for Amliro.sia? 

Andrew: We're always working on plenty of new project.s. 
We ju.st released our Internet search t(x>l, iSeek 
<http://wvvw,AmbrosiaSW.com/utilitie5/iseek/> that's going over quite 
well, and as 1 mentioned, IVe kid my head buried in Snapz 
Pro X 2,0, Tliat’s going to Ix" a huge prfxluct when it comes 
out, llic video capture |x*rformance is just amazing now. 
Additionally, weVe always working on cool new games, 
some of which we’ve anjioiinced, like our 3D racing game 
Redline, and others we haven’t. And you can't make me 
talk either. :) 

Tnj. Next Momtii... 

I hope you enjoyed tliis little respite from c'oditig. I know 1 
did, Part of tliis was getting to know someone w^ho has really 
lK“en a pari ol’ tlie Mac gaming story. But another fxiil ofthi.s 
montii's colunai was a bit of a stroll clown memory lane, 1 
mean, c’mon, Tliink Pascul iTti/bnni was bought by Symantec. 
1 loije itf!! © 
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New Privilege 6 


SECURE SOFTWARE eCOMMERCE 


Aladdin 


Generate new software 
revenue streams— 
securely, effectively. 


Selling, distributing and activating software 
electronically isn't new. But doing it securely 
AND all from one source certainly is news! 
With Privilege from Aladdin, you can have: 


Via the Internet; 

■ A secure ESD process, transforming casual 
sharing into a super distribution channel 
for trialware 


■ Increased customer satisfaction and loyalty 
with short and simple purchasing process 
and resumable downloads 


■ Instant access to international markets with 
multi-language support 


Via digital media and CD: 

■ Your choice of CD's^ or pre-loaded trialware on 
new computers, with flexible software activation, 
try-before-you“buy, and try-onfy 

■ Capture new opportunities with full control over 
licensing terms, offers and the user's experience 


Take advantage of every new revenue 
opportunity available today! Call us at 
1-800-562-2543, or visit GoPrivilege.com to 
receive a FREE Privilege information pack. 























MAC OS X 

PROGRAMMING 

SECRETS 


By Scott Knaster 

Checking Out Kiosk Mode Features 


Por about 20 yeans now, Apple has been telling us that 
modes in stjftware are bad. It's hard to remember, especially if 
you're a youngster, but we used to drive software around by 
getting into and out of modes, restricted places dint provided 
their own deliniiions for the way commands worked and actions 
were interpreted (kind of the way a lot of venerable UNIX text 
editors and command line t(x>ls Wf)rk in OS X today, except tills 
was for everybody, not just us geeks). For extimple, when you 
tyjx?d a slash into a little old spreadsheet prognim railed 
VisiCalc, you went into command mode, .signaling that die next 
chamtier was an instructj<m rather than somediing llial should 
apjKar in a cell. 

But Apple in its wisdom says mtxles are OK in certain 
situations. For example, modes that emulate the real world are 
permiiicd, such as picking a type of brusli in a painting program, 
Another kind of mcKle is u.sefiil when you intentionally want to 
limit what your tisers can do. Tills rare situation l>c‘comes reality 
when you consider the kiosk, a public computer that lias to 
fend for itself when accosted by clueless newbie.s, hostile geeks, 
and keylxiard-pounding toddlers* 

If you’re developing an application that has to run at a 
kiosk, Apple helps you out hy providing a set of features for 
kiosk mode in Mac OS X. In this column, we'll take a look 
at how lo take advantage of what OS X can do for you in 
kiosk mode. 

SiMPU API 

Apple put the ctxil new kiosk mode features into OS X 10.2, 
adding a little more in 10*3^ You get to the feature.s ihrtaigh two 
function calls: SetSystemUIMode and GetSystemUlMode. These* 
calls lei you effectively lock the user inside your application, 
preventing the hostile, curious, or ignoram froni wreaking 
hav(X'. Tlie SetSystemUIMode call is defined like this: 

OSSratufi SetSyfiteialjIHode [SystemUIHode inMode* 

SyatemUrOptioRS inOptions): 

The inMode parameter specifies the LH mode you want, and 
inOptions lets you chfx>se settings for that mode, 'fhere are five 


modes you can pick for your application, as shown in Uie 
fahowing table: 


System VI mode setting Details 


kUi Mode Normal 

The usual mode for all applications, 
and the mode you get if you don't 
make any calls to this API. 

kUIModeContentSuppressed Tliis mode pawents the system from 

dniwing anything into the txmlent 
area of the scaen ItcIow the menu 
bar unless the u.ser performs an 
adion that triggers an aulo-show 
behavior. In practice, this mode 
simply turns dock hiding on, which 
makes the dock vanish until the 
mouse pointer moves over it, 
w^liereufKjn it slides onto the screen. 
Note: this was broken in 10,2 and is 
fixed in 10.3* 

kUIModeContentHidden 

Tliis mode hide.s the dock - 
techniolly, all system UI elements 
other ilian the menu bar - and does 
not show it even if die user mouses 
into the tlock region. Note: this was 
also broken in 10.2 and fixed in 10,3- 

kUIModeAlf Hidden 

Use this mode to hide itic menu bar 
along wiili die dock, with no auto 
sliowing feature. 

kUlModeAllSuppressed 

This naxle was addcxl in 10.3. Use it 
for liiding the dock and menu bar. 
liuf in thi,s motle they will both auto- 
sliow' if the u.scT mouses over their 

content areas. 


Scott Knastcr has Ireen writing about Macs for a.s long as them liiivc iK-en Macs. Scott^s Ixjoks To VTrUe Macintosh Softu^fv and MadtUosh 
Prri^ranttnin^ Seavis w'ere tTecjiiired reading ftjr Mac pnjgrammets for mtire tlian a decade, Scx)tt w'ltHe dcwloper Inroks for General Magic and worked on 
Mac sottwarc for MicnxsoR. Scoti^a Ixxjks tiave Ix^en iranslatetl into Japanese and PascaL Scott ha.s every Issue of Mad magazine, wliich explains a lot. 
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When yon call SetSystemUtMode, you also gel to pass a set 
of options in addition lo lire mode you want to use. lliese 
options provide even more lock-in features for your kicjsk and 
help you further refine the imprisonment of your rowdy user, 
llere^s a list of the options you can ch(H>se: 


System IJl optkm l>€taiJs 


kUIOptionDisableAppleMenu 

Use this oplKjn u> disal^le ^jII 
items in the Apple menu, 
iilthoLigh despite the option 
niimc\ the appearance of the 
Apple itself isu^l disabled 
(must l>e a corpf^rute logo 
thing). 

kUIOplionDisableProcessSwitch 

Tilts option turns off the 
user's ability to swatch apps 
u.5ing Command-Tah and 
Commaad-Shift-Tab, 

kUIOptiofiDisableForceOuit 

if you select this oplion, the 
Force Quit item in the Apple 
menu is disabled^ and 
Command-Of>Lion-Escape 
doesn't do aiiyihing. 

Powerful! 

kUIOptionDisableSessionTerminate 

Tliis ription helps [irevent die 
user from shutting down or 
logging out. Wfien you use it, 
the Restart, Shut Down, and 
log Out menu items are 
disa[)led, Al.so, if the user 
presses the power button, die 
Resrart/Sieep/Cancel/Shut 
Do%vn alen wonT appt'ar 

kUIOptionAutoShowMenuBar 

This option is only valid 
when tised with 

kLilModeAlll lidden. l^ass it 
to make the menu bar show 
itscll’ if llic user rolls the 
mouse into its content 
region. 

kUIOptionDisableHide 

Tliis option was addcaJ in 
103. Set it to disal>le the 
Hide item in the appliciuion 
menu. 


Classic or Cocoa 
Applications? 

Ule LocaHnlHliii flll! 
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your fRtt copy oft 
the Guide to Translation and 
Localization - Preparing Products 
lor the Gtohal niarketplace 




Call: 1-800-878-8523 Email; fnfo@Untjosys.eom 
Fax: 1-503-419-4873 Or visit: www.Ungosys.eom 


Ule focus on what matters most: meeting your 
needs and prouiding excellent customer seruice. ^ 

• Translation • Localization 

• Desktop Publishing • Engineering 

• Project Management • Quality Assurance 



■, ^3TSmS 




15115 SW Sequoia Pkwy. #200 Portland, OR 97224 
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Fdftfe Quit 


tf an appIlcattQn doesn't respond for a while, 
select its name and click force Quit 


^ Acrobat Reader 
IS Entourage 
V Excel 
Grab 

Help Viewer 
^ iChat 
J3 iTunes 

MSN Messenger 
O NetNcwsWtre 
OmmOuiliner 
^ Preview 

Project Builder 
0 RealOne Player 
0 Safari 


You CJUT op«n thn window bur presini^ 
Command 


( force Quit ^ 

A 



Arc you »yrc you w»nt to sKmi down your 
comduvcr now? 


{ ee»!an ) ( Steep ^ ( Cancel ] f Sbwt 


to set any options, you atn specify your desire in the 
application's property list* Jusi add a key named 
LSUIPresentaiionMode with type nynilx.T and a value of 0, 1, 2, 
3i or 4* Use 0 for normal mode, 1 for content suppressed, 2 for 
content hidden, 3 for aU hidden, and 4 for all suppressed, 

*10 help you view the power of the kiosk tnode APIs in all 
their majesty, Apple provides a ctxjl sample app, called 
UsingsysiemUlMode, that demonstrates the various available 
features and tweaks. See Figure 2 for a shot of the app's screen. 


' K Q 0. _Uenw _ 

Ho^if miMjft! 4Mtr t, Ulnuxli (k MHWibian I'P Qtr a detaihtd diiiiCflpitiin 



figure 2. samfde uppUcution for testing kiosk mode 

APIs, 


To gel I he sample app and lo learn more about 
implementing kiosk mode in your application, see Techniol 
Note TN2(K)2. Guide to Creating Kiosks on Mac OS X, available 
at http://developer.apple,com/technotes/tn2002/tn2062.html. 


figure L VbK can use SeiSysteml^Mode to premii users from 

getting access to the force Quit and Pmm- uindom. 

One of ihe cautions to note in using SetSystemUIMode Is 
that the UKxJe you set is only respected when your application 
is frontmosl. If through magical incantation or other methml the 
user .somehiiw manages to bring anoilicr appliaUitin to the 
front, tile Ul mode for your application is switched out ak>ng 
with ilic rest of the app. 

rhere is a corresponding call to hnd out the current Ul imxlc: 

Gc!tSystO'i!iUtMoftc(Syjst€'jaUtMode *outt1ocJe* 

Syflti?tntJTOptlotifi 'outOptlcms); 

As you can guess, calling GetSystemUIMode gets the current 
ukkIc anil options, in case you need to know- what they are. 

IX-fX'iiding f>n vvfeir your kiosk does, you might want to make 
the Finder go away. One gtKxJ reason for tliis is that it prevents users 
from clicking on tlie desktop to switch mtt d' your appliaition. You 
ran get rid of the lantier by sending it a kAEQuitApplication Apple 
event. Apple has an example lo sIkjw you how to do tliat - it*s at 
http://developef.apple.a>m/technotes/tn 2 {X) 2 /dovimlo^^ . 

If you just want your appiic'ation to sian tip in one of ihe 
modified system Hi inodes and slay tliere, and you don't need 


No Can I>o 

Although the kiosk mixle AFl is a gtKxl start toward Uxking 
up yf>ur kiosk machine, tliere are some tilings youll want to tlo 
that you can't do yet. And ju.st w4ien you ihoughi cveiyiliing was 
perfect. Here's m<ire information alxait some of tliusc limitations: 

Yon can't disable the eject key. If your kiosk lias to mn with 
a CD or DV1> inserted, ycju can design the kiosk so that it's 
physic^iilly impossible to ejeci the disk. 

To dtsafjle vari(>us wacky scenarios, sLieh as taking control 
of the niachine by booting off an external disk or iKKalng into 
single-user mode by holding down Q>inmand“*S, you can enable 
the Mac’s Open Firmware password. When the Open Firmware 
passwoai is enabled, the Mac will only Ixait from the siariup 
disk you select in .System Preferences. 

You can't prevent the user from messing with the brighmess 
keys and darkening the screen, nor am you intercept ilie 
volume keys. 

One Moke Thing 

Needle.ss to say, kx’-king your irsers in and preventing them 
from having basic features is not a standard design principle. In 
a kiosk, many of lliese features are neemsary. in a typical app, 
they're practically criminal. Please use them with care, or at Icmst 
a sense of humor. 
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^^Vfithout a doubly the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools.^ 

- MacUniir Magazine Eddy Awards 

“A distinct improvement over Applets ResEdiL ” 

— MacTech Magazine 

*Every Mac OS developer should own a copy of Resorcerer'' 

- Leonard Rosentkol, Aladdin Systems 

"Without Resorcerer, our localization efforts would look like a ^ 

Tower of BabeL Don t do product without itr 

- Greg Galanos, CEO and President, Metrowerks 

“Resorcerer's d>ata template system is amazing." 

— Bill Goodman, author of Smaller Installer and Compact Pro 

“Resorcerer Rocks! Buy it, you will NOT regret iL" 

— Joe Zobkiiv, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and efforL" 

- MacUser review 



“The template that disassembles PICTs is awesomeP 
— Bill Steinberg, author of Pyro! and PBTmls 


“Resorcerer proved indispensible in its own creatkmr 
- Doug McKenna, author of Resorcerer 
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Version 2.0 



• Very fast, HFS browser for viewing file tree of all volumes 

• Extensibility for new Resorcerer Apprentices <CFM plug-ins) 

• New AppleScript Dictionary (*aete') Apprentice Editor 

• MacOS 8 Appearance Manager-savvy Control Editor 

• PowerPlant text traits and menu command support 

• Complete AIFF sound file disassembly template 

• Big-, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 



Requires System 7.0 or greater, 
1.5MB RAM, CD-ROM 


Standard price; $266 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it's easier, faster, and more productive than KesEdit 
Safer memory-hased, not disk-file-based, design and operation 
All file information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 

- » *1 and safely 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PO's, or Visa/MC 
Taxes: Colorado customers only 




All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit ve^ large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvenL GX, etc. 
Full integrated support for editing color dialogs and menus 
Try out balloons, ietb's, lists and popups, even create C source code 
Integrated single-window Hex7Coae Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


Ui Clliail LIS/ 

(X)D, FodEx, UPS Blue/Red, 


International Shipping 


MaTHEM^STHETICS, INC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
resorcerer@malhemuesthetics.com 


Try out balloons, ‘ictb’s, li 
Integrated single-window 


patching, searching 


Ih order by credit curd, or to get the latest news, bug fixes, updates, and apprentices, visit our website. 


www.mathemaesthetics.com 












CASTING YOUR 
.NET 


Andreu) Truelsen, Minneapolis, Minnesota 


Compiling, disassembling and 
re-assembling .NET binaries 


Exploring .NET development on Mac OS X 


Diving Deeper into hie .NFT Assembly Format 

Tilt: previous issue got you up and running with Lhe SSCLI^ 
and introduced you to the basics of die C# cx)mpiler (esc) and 
CU execution launcher (clix) utilities. In this insiallTnent, you will 
not only come to learn sonie additiomil options of csc\ hut also 
examine two key development uk)1s (ildasm and ilasm) which 
any .NET enthusiast must l)e aware of. Along the way, you will 
gain a much deeper understamling him a .NET assembly is 
composed under the hotxl. 

A Riivmw or Assembly Basics 
D uring the course of these first few insiallmcnls, you have 
come to learn that the .NET plaifonn supfxirts a high degree of 
binary reuse, which is made possible using a unit of 
deployment termed an mmnhiy, kentll that .NE'E assemblies 
(which may take an * *,exe, •xlll or Vneimodule file exiension) 
are composed of iliree key elements: CIL cfxle, type metadata 
and the assembly manifest: 

• Common Intermediate Language (CIL): The true 
language of the .NET platform. All .NET-aware compilers 
tmnsform their respective tokens into the syntax of CIL. As 
noted cariicT, CIL code is conceptually similar to Java 
bytecode in that CIL is platform agnostic. Unlike java 
bytecode however, CIL is compiled (not interpreted) on 
demand by die .NET runtime. 

• lype Metadatas U.sed to fully describe each and every 
aspect of a .NET type (class, interface, stnicture, enum or 
delegate) referenced by, or defined within, a given 
assembly. As you get to know the .NET platform, you will 


quickly discover that type metadata is the glue for every 
major technology. 

* Manifest: Metadata that descrilies the assembly itself 
(version, required external assemblies, copyright inftjnnalion 
and so forth). As tiescribed at a later lime, the assetnhly 
miinifest is a key asjxcl tif the .NET versioning policy. 

The good news is that you wall never have to author a 
lick of CIL code, type meiadaia or manifest information by 
hand, as it is the job of a NH'I" compiler to translate your 
source code into the correct binary formal. Given this, you 
will never need to <lescribe your types manually (as is the 
case in COEbA 11)1.) or build C-based wrapper classes to 
comniunkate with an underlying protocol. While the .NET 
platform support.s multiple language.s and corresponding 
coinptlers, few would argue that is the language of choice 
used to I mild .NET assemblies. 

In the last issue, you creared a .NET t'odc library CMyLib.dll) 
and a corre.sponding .NET client executable (MyClient.exe). 
While you are free reu.se that source ctxie over the tour,sc of tliis 
issue. Listings 1 iind 2 offer a few simple types \o manipulate 
over the pages ifiai follow. 

lisimg j: simpk'CtidciibRry.cs 

// \ simple anlc librio (iiic class lypc. 

uising Syirtcm: 

namespace ShamErLJb 
I 

public class Shamir 
( 

public static void SharaeChild (Btririg kidNania, 
im intensity) 

I 

ioidnt i “ 0: 1 < Intensity: i++) 

Consol0.tfritoLlRc("Bti quiet tOlll". kidName): 

1 

I 

I 


Andrei' Troelsen is a seasoned .NET develojx^r who has authored numerous books on the topic, including the awjml \\ inning C^aud the .AA7 
Ptal/onn. He is employed as a full-time .NEL trainer and coasiiltanl for InterttH'h Training (www.intertechtraming.com), and is a weU-known Timfxrwolves, 
Wild and Vikings ruhe (nor necessarily in that order). You can contact Andrew at atroelsen@mac.com. 


Compiling, disasskmjhjng and RE-ASsiyitnuNG .NET litNAKirs 
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Bob and Sue use a MAC for business, 
but their accountant uses a PC. 

Do you know what kind of 
accounting software they need? 




H [iiiiiiii. That umki lie a proHlem, but not with MYOB* 
Despite their different operating systenis. 

Bob and Sue and their very clever accountant, 

Nick Tlic Numbers Man, are able to manage 
finances, create reports, and pnxlucc documents 
as easy as can l>e. 

MAC or Windows-it makes no difference, they 
donV even have to be in the same place at the same time. 






Tliey can do it all by e-mail so quickly rhar theyVe able to dcvocc 
more time to their favorite customers and clieoLS* 

^ Wherever you arc, whatever the platform, MYOB is the 

accounring software rhars a smart choice for everyone. It 
turns everyday accounting and financial 
management into something thats almost fun. 

MYOB, 

THE SMALL BUSINESS ANSWER. 

^2003 Uij. i YOH WWW. m ya b.t oiti f Li* 






















Lisikg 2: ^impkOient Application cs 

// Chir client appJkution makes use 
// of Siliaoicr.dii (seen in listing l>. 
using Systepi; 
using SharaerLib: 

namespace ShamerCiient 
1 

public class TheApp 
( 

public sLalic void Hainistringf] args) 

I 

string kidNamc: 
int frustratlonLevel: 

//AH ,NET arrays derive fioin System Array. 

//Hus claLss type has a memtjcr n:uned Length, 
if[args*Length != 0) 

[ 

kidNaiae = args[0]; 

frustratiouLevel liiL*Parsc(args [l]) ; 

I 

else //Nocommand Hncargs,prtjmpt user. 

I 

Console.Wrlte('Tlease enter child's name; : 
kidNamo = Consnle,ReadLirie[) ; 

Console,Write("Please enter annoyance level: 
frustratloriLevel ^ i nt. Parse (ConBole^KeadLine f)) : 

I 

// Pas-s user input to SlianitT type 

Shamer.ShameGhild[kidNatne, frustrationLevel): 

Console.WrtteLlne("Thanks for playing..,"): 

I 

1 

I 

Hie only lejil point of interest in LLsling 2 is the liid that we 
have provitied the ability to pn:>eess tx>niniaixi line argiinients via 
the iticoniing an:ay of stnng.s, it Uie caller ck)e.s supply such 
argiitnents, we will iLse them to iissign our Icxtil variai>les (kidNaine 
and fnistiTitionlevel). On the other hand, if the user dtx^s not siijyply 
etantnand line aiguments, s/he will Ix" prompted at the 'terminal. In 
either case, once the Uxal variiihle.s have Ixen assigned, tliey are 
jiiissecl into the static ShanxTLil).S]iaitier.SiiiaiieChikl() method 
kxated in tiie shamer.dll assembly* 

Rinij> Details of ihe C# Compiler 

Now that we have some source code at our disposal, 
let’s examine select details of the tSSClJ compiler, esc. The 
compiler tcsc') is a command line itK)l wdiicli suppoits numerous 
arguments, the full set of which can be viewed by typing rlie 
command shown in Listing 3 from an SSCU-enabled Terminal 
(see the previous issue foi- details regarding soureing the SSCLl 
environment variables): 

Ustiiig 3 Viewing each tipiion of esc. 

CSC -h«^]p 

Now, assume you wish to compile .simpleCodelabraiyxs 
into a single file assembly named shamer.cllL To do .so, yt>u 
need to be aware of the following core conimands of c.sc.exe: 

• /target: Allows you to spec'ily the foJTnat of die output file 
(code liixaiy, Terminal application and so on). May he 
.shortened to A:. 


COMIIUNO, niSASSHMBtJNG AND RH-AS.SFMHUNU .NET BINARIES 


• /auL Allows you to specify the name of die output file. If 
(Htiitlcd, the name of the output file is based on the name of 
the class which contains the MainO method, or in the case 
of a class library, the name of the initial input file. 

• /reference: Allows you to s]?ecify any external a.ssemblies 
to reference during the airrent compilation (may lx 
shortened to /r:). 

At it's core, esc processes C# source code files (whic*h by 
convention take a *.cs file extension) to produce a binary file 
termed an assembly. Under the SSCLl, esc provides duee valid 
flags dial control the target output (liable 1). 


Option of /target fkig 

Short Form 

Meaning in life 

/target :exe 

/uexe 

Genenire.s an cxecuiahle 
Terminal assembly with 
the *.cxc file exlenskin. 


/l:dll 

Generates a i>inaiy code 
library that 'may not \k 
directly executed by ihe 
.NET’ runtime. Rather, 
*.dll binaries are loaded 
by an executing •.exe. 

/taiget;m(KJule 

/t:nKjdule 

This option allows you to 
build a 'multi file^ 

assembly. In a nui.shell, 
mtJlii-file asscmblie.s 
a col lection of code 
library files that are 
intended to lx versioned 
as a single logic;il unit. 
'Fhis particular aspect of 
,NFrr will lx examined at 

a later time. 


TahiL* L Wriatimis of ihe flag 


In addition to the /t:exe, /t;dll and /t:nifKlule files, the esc 
compiler of the SSCLl also supplies the /taigeUwinexe flag, which 
effectively dexs nothing under the Macintosh operation system 
(under CjlJI-aware im|>lejneniations of the compiler, /tiwinexe 
i.s iLsed to build a GUI-based Windows Forms appikmion). 

Of counse you will al.so need lo sfxxily the .set of input files to 
lie prcx'essexl. Thc'se can lx listed individually a,s discrete arguments, 
or via the wildcard syntax (e.g., esc to in.smui csc.exe to 
amipile all files in the tiirremt direaory. Ht?wever, to build 
shamendli, the following aaiuiiand set w^ill do nicely ( listing 4): 

Lisiuig 1 0>mpiling ilic Sbamcr.tiJI emte tibran'. 
CSC /l: library /aunshanier .dll 0 iiiipleCodeLlbrary,es 

To compile siinpleClieniApplicaiion.es into a single file 
executable as.sembly thui makes use of the types contained 
within shainer.dll, enter the command shown In lasting 5 
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(be sure rhar shamer.clll is in the same location of the input »inpui files. 

*.Cs file): flrstClass.es otherClass.es thirdClass.es 


IJstitifi 5. Clomptiinji the client.exe eveciitahlir. 

CSC /t:f?xe /out tel i ent. exe / r: shomcr . dl 1 
slnpleClletiLApplleation. es 


Given this, you can now sitnply pass in the 
compilerArgs.r.sp file as tlie sole argument to csc.exe via liic 
flag (listing 9): 


At this point you are jHq to run the resulting client.exe 
applicaiion (either with or without command line arguments) 
using the clix utility (Listing 6). 

Ibiing 6. Uxeeuiiiig your .Nil' cxunipk' applieyLion. 

clist client.exe Sally 9 

Here we are passing two argumenis to the clieni.exe 
application. Recall that we have programmed MainO ro parse 
tiicsc values out of the incoming anay of strings, and 
therefore the phrase "Be quite Sally!!" will print out nine 
times. If you run clienr.exe without specifying any command 
line arguments, you will be prompted at tlie Terminal for 
further input. Do note that the version of MaiiiO is not smart 
enough to receive these arguments out of order (just to keep 
focused on the tasks at hand). Given this, if yon specify the 
child's name after the irilensity levef you will receive a 
runtime exception. 

Working witli C# Response Files 

When you work witli the C# command line compiler, you 
are likely to issue the .same option.s during each compilation 
cycle. For example, assume you have a directory wliicli contains 
ten *.cs files, of which you wi.sh to compile three of them ititc^ a 
single file .hTET cias.s library named MyLih.dll, Fuithermore, 
as.sume you need to reference various external assemhiie.s for 
the build (listing?); 

listing 7. A non trivial esc comn.iJ.nd set. 
CSC /out: My Lib .dll /t: library /r:Kyatein.Xinl.dii 
/r:MyCoolkib.dll /riMyOtherLibtdil firstCiass.cs 
otherClasa.es thirdClass.es 

Clearly, this can liecoiiie a pain. To help miike your 
Terminal compilations more enjoyable, the compiler supports 
the list.* of Tesponse files’. The,se text files (which by convention 
take an *.rs]> file extension] contain all of ilic options you wi.sh 
to pass into esc. Assume you have created a response file 
(Listing 8) nameti ('ompilerArgs.r.sp (note that comments are 
denoted with the symbol): 


l.isiing B. CoiiipiterAi^.rsip. 

# canipilcrArgj^.rsp. 

# Nnnit of ouipiu file. 

/out:MyLib.dll 

^T>'pe of output file. 

/tGibrary 

# External assemblies to reference. 

/r:System.Xml.dll 

/riMyCoolLib.dli 
/r:MyOtherLib.dll 
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Ustinj; 9.Sp<.T(frinK a resptmw nif ai tito eomiiiami line. 

esc @e:ompiletArg,s. r£ip 

If yt)U wish, you may feed in mtilliple re.sponse files 

(Listing 10): 


Listinj> lO.cse may Ix' fed in multiple response files. 
CSC eccjinp.tlerArgs-rsp @itioreArgs . rsp @fiv<5iiMoreArgs. rap 

Keep in mind however that re.sponse files are proce.ssed in 
the order they are eneounlered; therefore .sellings in a previous 
file can be overridden by settings in a later file. Finally, be 
aware that there is a 'default' res|T<)nse file, c.sc.rsp, which is 
auloniatically processed by csc.exe during each compilation. If 
you examine the contents of thi.s file (which is located by 
default under /.sscli/buikl/vTppcfstchk.rotor) you will lind little 
more than a set of common assembly references (suc h a.s 
System .dll, System.Xmfdll and so on). In the rare occasion that 
you wish to disable the inclusion of c^c.rsp you may specify’ the 
/ncK-onfig Hag. 
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Of course, the C# compiler defines mmy other optiojis 
l)eyond the set we have just examined. Over the life {jf the 
series, yoiill .see additional options al work, liowever check out 
/sscli/docs/compilers/csharp.htinl for all the gor>^ details of the 
CSC utility which sliips with the SSCT-h 


,ver 0:0:0:0 

1 

♦assembly client 

.hash algorithm 0x00008004 
-ver 0:0:0:0 


Till- Roll oi thl CEL Dissassembixr (aoASM) 

At this point you should be confident in your ability to 
build and debug .NET assemblies using esc fof course, 
itself may still be a bit of a mystery, but well deal with that 
soon enough). Ihe next topic to address is the process of 
getting under ihe hood of a binary NET blol> and cheeking 
out tile key ingredients (CIL, type metadata and manifest 
information)^ The SSCLI ships with numerous programmer 
tools ro do this very thing, the firsi of wfiicii is the 
Intermediate Language Disassemlder tildasm). Table 2 lists 
some of the key options of this (very insightful) utility (see 
/sscli/docs/tool.s/ildasm.html for full details). 


Option of ildiism Meaning m life 

/ciassllst 

Displays a li.st of alt types within a given .NET 
assembly. 

/item 

This (jpiiun allows you to view the dis;jssenibly 
of a .sjminc type or type member, rather tlian the 
entire set of tyjue mcmlx^rs. 

/metadata 

Use this flag to view' the type metadaUi wiiliin ihe 
.NET assembly. 

/(nirput:<filename> 

In.smicts ildasm to clump the contents to a 
specified text file, rather than to the Terminal. 

/ visibility 

I'hLs Hag instrucis ikiasm to display types tif a 
certain visil^iiity’ level, hi a nutshell, C> supports 
the creation of public types (which may Ixr used 
by Ollier assemblie.s) and internal ty|X’s (whkTi 
may only he Li.sed by the rlefining assembly). The 
CIL programming language dcfiiiCvS a niimIxT of 
addiUona 1 Visi! >ilily mot 1 iflers. 


Table Z Some (huf fiot afl) optiom of ikkmri. 


do take this tool out for a test drive, let's view the internal 
simcitire of tlie entire t lienLexe assem[)ly (Listing 11). 


ildfif3iii client.exe 


Lining n. Uisasscnihlin^ dicnLcxc via iltbcijii 


Viewing the Assembly Manifest 

The first poinl of interest is the manifest data, whieli as you 
recall is metadata that defines the assembly itself (listing 12). 

12. The manifest dnin of dieni.exe 

.assembly extern mscorlib 
( 

.publlckeytoken - (B7 7A 5C 56 19 M EO 89 ) 

♦ver 1:0:3500:0 

1 

.assembly extern shamer 
1 


.module cltent^exe 
•imagebase 0x00400000 
.subsystent 0x00000003 
.file aligTjinent 512 
.corflags 0x00000001 

The critical point here is the use of the .assembly extern 
directives. These CTL token are used to document the set of 
external assemblies the curreni assembly must have to 
function correctly. Notice that elienuexe makes use of the 
standard niscorlib.dll assenilily as well as (surprise, surprise) 
shamer.dlL Next, notice that the .assembly directive (without 
the extern attribute) i.s used to describe basic eharacteristies of 
the ciirrcni as.scmbly (clicnLcxe in this case) such as ids 
version (.ver) and module name (.module). As mentioned, the 
.NET runtime read.s this information during the process of 
locating and loading external as.semblies for use {exactly how 
is tlte topic of a later article), 

Viewing the CIL behbid MainO 

Next, let's examine the CIL ccxie produced by esc for the 
client’s .static MainO method (Listing H). Be aware that each of 
the ll_XXXX: tokens are line-lalx.'ls inserted by ildasnu 


Listing B, I'ht! OL uf MainO. 

method public hiftehyfiig fitjstle veld 
Ktiin (string [] args) cil managed 

•entrypoint 
.maxstack 2 

.locals init (string V_0. int32 V_l) 

TL OOOQ: Idarg^O 

Th^.aODl: Idlan 

Tli_0002: con V. 14 

IL_0003: brfslso^s IL_0014 

1L_OOU5: Idiitg^O 

IL_0006: Idc,i4,t3 

IL_0007i Idelem.ret 

IL_0008: stioc.O 

1L_0009! Idarg.O 

IL 000a: ldc.i4*l 

TL_00Dh: Idelcm.ref 

TL_onDc: call int32 ImsCDrlib] 

System.InL32::ParsG(st f Ing) 

1L_0011: stloc.l 
IL_0012; br.s 1L_0039 

I:L_OOU: idfitr "Please enter child’s name; " 

IL 0019: call void fmscorlib] 

System,Console::Write(string) 
rh_001e: call string, [mscorlib] 

System.Console::BeadtJ no(S 
IL„0023: slloc.O 

1L_OOZ4: idstr "Please enter snnoysncG level: " 

1L„0029: call void tmscorllb] 

System.Console:;Write(string) 
tL_002e: call string [mscorllbl 
System.Console::ReadLine C) 

TL_0013{ cal] lnt32 ftnEcorlib] 

Syslcm,Tnt32;:Parse(string) 

IL^0033: stloc.J 
iL_0039: Idloc.O 
IL„003a; Idloc.l 
IL_003b: call void LahamerJ 
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ShsffletLib.Shamer::ShameChild[string, int32) 

IL_0040: Idstr "Thanks for playing.*," 

IL_0045^ call void [pKcorlib] 

SysLcin. Con solo:: WriroLi no (string) 
lL_G04a: reL 
j // ond of mfUicxrnicApp::M;iUi 

Now, before your eyes pop out of your head, let me 
reiierale lhai this is nol I he place Lo dive into all the details 
of the syntax of CIL, However, here is a brief explanation of 
the highlights. 

First of all, CIL is an entirely stack ha.sed language: values 
are pushed onto the stack using various CIL operational codes 
(opcodes) and popped over the stack using others. Notice that 
the MainO method Is adorned with the .entrypoim directive, 
which as you may guess is how the .NtTf mntinie is able to 
identify entiy' point to the execurahle. 

Next, note that the .rnaxstack dircaivc is used lo mark the 
u[)f)er limit of values which may be pushed onto the stack 
during ilie duration of this nietlxxL Given that our MainO 
method defines only two loc'al variai)les and never aills methods 
with more than iwu arguments, it should Ix' no suq^rise the 
value assigned to jnaxsiack is 2, 

Now, notice the syntax used in invoke a type method 

(Listing 14). 

Uiiinti 14. Invdkinj* Cunsok,Wrik'0 mil SliankrrSlumidJliUdO 

TL_0DJ9i call vnid [piscorllb] 

SysLenuConsole::Writc(airing) 

lL_0U3b: call void [ahamf^r] 

ShamerLib*Shan3er: :ShaineChiid( string. intJZ) 

A*s you can see, the call opcxxle marks the act of invocating 
a method. However, notice that the frit'ndly name of the 
as.seTiil)ly i.s infixed lietwecn ilic retuin value and method name. 
Given this, we can boil down a CIL method invocation to tile 
following simple template showm in Listing 15: 

IbitinK IS.lilt: OLof niohixl inv<3Cjikin.s. 

ReturnType [NameOf AfiFiGirihl y] 

NaiJEuspac e * Typo:: Mo rhod Kame {a nyArgumcn ti? ] 

Again, don't sweat the details of CIL at this point in the 
game (in fact, you can live the life of a happy and healthy 
developer witlioui iliinking alxiui CIL whatsoever). Simply 
understand that the ildasm Uxil allows you to view' the raw CIL 
syntax emitted by a given .NLTf compiler. 

Viewing the IVpe Metadata 

Recall that an assembly is composed of three key elemenis 
(Clt*. type metadata and manifest infonnalion)* If you was!) lo 
view tlie iy[)e metadata vvitliin a given ai>.sejiibly, you must 
specify the /metadata option (Listing l6). 

I.isiing 16. listing t>p<^ metiulm with ildism 

ildasm /roeLtxdtiLa clU*nl.exe 


Once you execute tliis coiraiiand, you will find that the 
initial output of ildasm is indeed a listing of type metadata. 
Simply put, .NKT meiacLita am be lumped into two c:alcgories: 
Tyf>eDefs (types you defined yourself) and TypeRefs (types 
within an external asseml:)Iy you referenced). Both of these 
categorie,s will lisi in vivid detail the comfx^sition t)f each item 
(e.g. l>ase class, number of metliods, method parameteis, etc). 
For example, Listing 17 shows the metadata for the 
ShamerClienr.TheApp class type defined within ciient.exe 
(again, don’t sweat the details). 


Usiirig I7.iype iieiatlata forllicApp 

// TypeDef /fl 


// TypDefNajrf}: Shamp-rCl ient ,TheApp (0200000?.) 

// FlagtJ : tPublic] lAatolayout] 

// [CUsa] [AnsiClass] (00100001) 

// Extends : OlOOOOOl [TypeRef] Sy^Jl^tIl.Object 
n Method #1 lEmrPOlNTJ 

n . ..... 

// MethodMaae: Main (06000001) 

// Flags : [Public] [Static] 

// [HideByStgl [ReufseSlQt] [00000096) 

// RVA : Qk00002050 

if implFlags 1 tiL) [Managed! (GOOOOQOO) 

// CallCnvntn: [DEFAULT] 

// ReturnType: Void 
// 1 Arguments 

// Argument #1: SZArray String 
// 1 Parameters 

// (1) ParamTnkon : (OSOOOOOU Name : 
if args flags: [none] (00000000) 

if Method #2 

if ----- 

// HethodName: *ctor (06000002) 

// Flag.^ : [Puhlic] [HideBySigl [ReuseSlot] 

// [SpocialRsme] [RTSpecialNaTne] [.ctnr] {00001&S&) 
// RVA : OxOOOOZOaB 

// Itnpltlaga : [IL] [Managed 1 (00000000) 

// CallCnvntn: [DEFAULT] 

H hasThls 
if ReturnType: Void 
// Mo arguments* 


Now, you may be wondering whai use type metadata 
serve.s in the .NET platform. To be honest, just about 
iwrythinf> in .NET revolves around metadata in one form or 
another, Clhject senalization, XMI. Web sei'vices, .NE'f 
remtHing, late landing, dynamic type creation and heap 
allocations all demand full type descriptions. Later in this 
.series, you will learn henv to leverage tliis information 
programmatically using the friendly object model provided 
by the System.Rellecticm namespace (can anyone say custom 
object browser?) 


Tuii Miri'AlNj o UriuTV 

On a metadata-related note, the SSCLt .supplies an 
additional tcKsI (metainfo) which is used exclusively to view type 
metadata (see /sscIi/docs/tooLs/nietainfo-htnil for full details). 
[*or example, if you wish to see the dypeDefs and TypeRefs 
within shamer.dll (but don’t care to see the Cll ccxle or manifest 
data), you could etUer the following command (Listing 18): 


li!>ting IH.Wijridog with tilt meiiiinfo utility. 

metaiiifshamer.dll 
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listing 19.An example usmj; rjvv Cll. 


The Role of the CIL Assembler (ilasm) 

Now that you can disassemble a .NE'f assembly using 
ildasin and meiainfo, il Ls worih pointing out that the SSCLl 
slu[ts with a CIL assembler utility named (not surprisingly) 
ilasni. Although it is not terribly likely, it is entirely possible 
to build an complete .NFT applkaiion using raw CIL code 
and bypass higher level languages such us VILNET and 
so forth (remember, as far as the .NUT runtime is concerned, 
it's all CIL). As suggested by Table 3, w'orking with ilasm is 
tjuite straighirorward. 


Options of ilasm 

Meaning in life 

/clock 

Tells ilasm to display compilation diagnostics for 
ihe currenl Iniild, 

/till tir /exe 

f?iiilds a code fihrary or executable assembly 
(respectively). 

/out pul 

Spedlies the nanre tji'llie taiipui hie. 


Table 3. Sotne (hiM not ail) options cf ifmm. 


As a fellow prognimnier, Fm sure you'd love to build a .Nh“l' 
assembly using Cll. and the CIL assembler iit feasi once (jusi to 
say you did it). Again, building anylliing but a trivial CIL source 
code file would require a solid Lindersianding of the syntax and 
semantics of the (Common Intermediate litnguage, how'ever if 
you arc up for tlie ta^sk, create a i)mnd new source code hie 
named simpIeCILC<xle.il (by convention, CIL cocle hies take an 
*.il extension). Within your new' hie, define the following .NU L 
type (listiug 19): 


// mscDflib.dil is smtomaiically 
// listed in the manifest by lh\m, 

// we dtm'i need lo txjlher speeifyiti|? 

// this external asseitibly, 

// N<m^ defined mir oxsembly. 

// If unspeeified, the version 
// (if an assembly is autnmaik^lly 
// 0.0.11,0. 

.ass embiy Simp1eClLCo de1j 
.module SiinpleCILCode.dll 

// Our unJv' eluss type: MydltixampIc.J’djllLApp 
.nataespace MyCILExample 
I 

, el a ns public aura befnref iel d I n i t MyCITiApp 

extends [ciscorlibl SyBt.e?iP.Object; 

f 

//jlic .single nieilmd. SpeakO. 

.method public hidebysla static void 
SpeakO cil managed 

I 

.maxstack 1 

Idsrr ■'Y ofr 

call void IniGcorllb] 

System.Cpnsole;^WriteLine(string) 
ret 
I 
I 

1 

Basically, tJtis CIL code lile defines a single namespace 
(MyClLHxiimple) which contains a single class (MyCILApp) 
which supports a single method named SpeakO. The 
iinplcmcntaiion of S[:)cak() loads a string literal tjnto the stack 
(via the Idstr opetKie) w^hich is u.sed for the invocation of 
System.CorLsole.WrireLine(). ibe ret opcode, obviously, returns 
from tile method. Now, to compile this CIL source code hie inttj 
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d binary supply the tbllowing coniniand set to tiasm 
(Listing 20): 

[jiitinji 20.<"t>mpillng 'il Hies usiiiR ihLsm 
ilasm /output: Sltnple.dl] /dll SimpleCILCode 

At this point, you can make use of Simple,dll just as you 
would any other .NET code library. I'o prove the point, let's 
update our existing simpieClieniAppliraiion.es file to invoke the 
SpeakO method (Listing 21). 

LLsUng 21. Our updated client application 

using System; 
using ShamecLib: 

// Need this! 

using HyGJl-Exaraplet 

namespace ShamerClient 
I 

public class TheApp 
I 

public static void MainCstring[1 args} 

I 

MyClLApp,Speak(}: 

I 

I 

I 

Now recompile clienl.exe wiiile referencing simple.d!l 

(Listing 22). 

Usijiig 22, Recompiling djcnL.LXc 

CSC /rtsimple,dll /rtshamer.dll /t:exe /out;client.exe 
slmplcClientAppi 1 cation»cs 

Sure enough, if you run simpledieniAppltcaion.exe through 
ildasm, you will find Simple.dll listed in the assembly manifest, 
Likewise, if you iim the updated application, you wdll find that 
the message (“Yo!!”) is emitted to the Temiinal. 

Round Trippin’ (Assembly to CIL, CIL to Assembiy) 

(liven the funcEionality of ildasm and ilasm, the SSCLl (as 
well as other .NET phitforiii distributions) iiitriiisically supports 
the notion of a Tound tdpL Simply put, this sofrw^are idiom is 
used to describe the process of coni[)iling -> decompiling ’> 
editing -> recomjiiling a software blob into a new modified 
unit. As you would guess, this can prove extremely helpful 
when you need to modify the contents of a .NE1' assembly to 
wliieh you do not have the original source code files. To 
solidify the information presented in this is.sue, try the 
following rcnind-uip exercise: 

* l)isa.ssemhle your client application using ildasm, outputting 
the CIl to a new file named sinipleClientApplicaiion.il (don't 
forget the /outpui Hag of ildasm). 


• Using your text editor of choice, modify each string literal 
(e.g. "Please enter child's name") to a new sUring ("Yo dude! 
Enter the name of the kid!"), 

• Save your changes and recompile the *.l 1 file mto a new 
executable assembly named ModifiedApp.exe using ilasm. 

• kun your McxlifiedApp exe assembly using clix. 

A Brief Regarding Obfuscation 

Now olwiously, if a .NET assembly can be so easily 
disassembled, modified and recompiled, you are no likely 
already imagining numerous doomsday scenarios (your 
proprietary 'bubble sort' algorithm has been modified to wipe a 
user’s hard-drive of all data) and copyright infringements ("But 
that is oi'^r CIL code, you can’t change it!”) Yes it is true, given 
that a .NET binary can always Ite viewed in teims of its CIL code 
using tools such as ildasm, it is possible tiiai prying eyes could 
rake your intellectual property as a basic for their own and build 
a soil ware monster. This problem is not unicjue to the .NET 
platform liowever, as numerous Java, C(++) and BASIC 
decompilers have existed for years. 

However, if you wish to lessen ihe chances of bad fx;oplc 
using your resulting CIL code for evil puiposes, rest assured that 
numerous .NET ohfuscators exist. As you imy know, the basic 
role of an obfuscator is to make use of a set of algorithms 
translate valid syntax (in this case CIL code) into and out-of total 
non,sense. As well, tiie ,NET platform supports the notion of a 
'strong name' which can be used to digitally sign (in effect) your 
assemblies using public / private key cryptography. By doing 
so, it is next to impossible foi- an evil individual to modif)^ a 
l>inaiy as.senilily and pretend to 'be you'. More on strong names 
at a later time. 

Wrap Up 

Sweet! S<.) here ends another inslallmeni of Casting yt>ur 
.NET where you spent your time digging deeper inta tlie 
ffimiiit of a .NET as.semb]y. We began by revisiting the key 
elements of a *NFT binary (CIl, metadata and manifest 
information) and learned about .some additional functionality 
provided by c.sc. Next up, you came to understand the rtile of 
the ilda.sm utility and learned how itiis tool allows .NET 
developers to peek inside the assembly itself to view the 
underlying goo. Finally, ytm took ila.sm out for a test drive and 
preformed a simple Touiid-tripL 

In the next issue, you will finalize your initial look at the 
SSCLl and examine a number of interesting sample 
applications, alternative .NET programming languages and a 
few additional development utilities. After tliis point, the 
next several installments will dive headlong into the details 
of the C# programming language. Until rhen, as always, 
happy hacking. 
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By StiVe Gehrman 


A simple debugging tool for Cocoa 


Another weapon in the fight against bugs 

Here's the prohleni: You write an application, test it, lix 
the hit^s and everything works great while testing indiouse. 
But, the moment you send it to the cii.siomer you get a ton 
of hug reports. 

How could this be? You tested the code thoroughly, and 
you've been running the application for months throughout 
Ute development process. YtmVe now getting hug reports 
yoiiVe never seen f>cfore. What happened? 

The problem lies in the fact that it’s just not possilile for 
the developer or even a small team of indiouse testers to 
uncover all the hugs no maUer how hard they try. Software 
is just rt>o complex, and there are just too many variations in 
machines, OS versions, and interactions wiili other installed 
software to catch everything. 

So, wdiat can you do? The only solution is to have your 
users help in the testing/ciehygging process. These 
users/testers are commonly referrt‘d to as beta testers. 
Tltere's only one problem with this solution. Your beta 
testers aren't devek)pers, and have no clue how the ctjde 
works, so the hug reports you receive may not he easy to 
decipher or reproduce. What you really need is a fool proof 
way for a user to report a problem automatically with 
in formation in a form that helps tlie developer determine 
what went wrong. 

In this article, I explain a simple technique for doing 
this. Using this technique, when a pn^hlem occurs in your 
application, a wimlow will appear with information 
des('rihing what liappened, and a stack tract* of where the 
prohleni occorred. ’['here is also a button in the window to 
automatically email this informatitm to the developer, 'that 
way, all the developer has to do is check their email, 
examine ihe reports, and fix the hugs. Sounds cool, right? 

The key to this debugging tool is exceptions. Most 
Cocoa objects will throw' an exception when passed a bad 
parameter or when something unexpected happens. 
Catching and displaying exception information is the key to 
this debugging aid. Catching exceptions can't find every type 
of software hug in your application, hut it will uncover a 
surprising number of problems and uncover lots of trouble 


spots in your code. IVe been using this code in my own 
application, "Path Finder," for two years now, and it has 
proven indespensihle. 

The remainder of this article explores tite cixle u.sed to 
do this and explains how it works. All the code is 
downloadable in a simple example application. If youTe like 
me and like to see the working code before reading the rest 
of the article, download ihe example application here from 
the MacTech website at www,maclech.com/src/19.12. 


Tiii; Coi>ii: 

CtKxxi has two built in classes for exception handling: 
NSException and NSI-lxceptii^nHandler. Tliese two classes are 
located in the ExcepIionHandling.rramework. The first step is to 
add this framework to your appliaitkm. I'm using XCcxIe, so to 
do this I go to the “'Project" menu anti cluiose "Add 
I'rameworks..,'* and navig;tte to /Systcm;Tibrary/Frameworks/ and 
chfKxse Exc^epiionHandling.fniiitework. 

Let's .start by U>oking at the NSExceptionHandler cla.ss. 
NSExeeptionllandier Ls really simple and dims tlie work of 
telling us when an exception has occurred in our application. 
All we need to do is create a delegate object that will he sent 
a message when an exception occurs. 

I created a class callcxl NTExceptiunnancIlerDefegare to do 
this. Here's die code, ids very short. 

Simple men tat ion NTExceptlonllandlernol ogate 

t id) ItiltWitMtTiftil: CNSStrinj^*)eiaaxJ-AddresiO 

i 

self = [super lirltl: 

^emailAddreaa “ jema11 Address ratainl: 

I [KSEatceptionHandler defauJ i Except ionHandlot 1 
cotDelegate:self]; 

[[iSExcepttonHandler defaultExceptlonaandlet] 
s et Eic c c pt i cinUa n d 1 i n gHa ek: N SLog And Ha nd 1 e£ve r c e p t i o nKa sk ] : 

return self; 

] 

- (void)ilealloc; 

I 

[[KSExceptionHandler dafauitExceptiouUandler] 
setDelegatejiilll : 
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setDelegateinilJ: 

l_emaiiAddress ; 

[sup^r dealloc]; 

1 

// iLsnl m Jiticr out stiitu^ aMiiittou iLtnulcfs^s exceptions 

CBOOLlsliouldDisplayException: (NSException *)os(copt;lon; 

NSString* name “ [exception name] ; 

NSString* reason * [cxcoptlori reason]: 

if ((naire isEquolToStriag;@’'NSIiBag€CacheException" 1 \\ 
[name isEqoalToStrlng:§'*CIFReading£xceptloti"| | | 
[name isBqualToString:@"NSRTFExcepticin^] j | 

([name 

isEtjuHlToString:@''NSInternfllInconeifltencyExceptlon"I 
I reason hasPrefix:lockFocus"]) 

} 

I 

return NOi 

I 

reLurn YES? 

I 

- (BOOL)exceptioniJandler : (WSExceptlonliandler Msender 
shouldLogException:(NSException "lexception mask:(unsigned 
inx)aMaBk: 
i 

// this atntntLs whether the atcepiioti shews up in the console, just femm YES 
return YES: 

1 

’ {BOODexeeptionhflndlor; (NSExceptionlfandler *)sender 
shouldHandleException ! (I^SExceptian *)exception mask: (unsigned 
intlaMask: 
f 

// if the exception isn't filiercd by shouldDispUyExecpikm. disj>l:iy the information 
to the user 

if ([seit shouldDisplayExcRpTton: exceptlori]} 

L [NTExceptionPanelCont rolIcr alloc] 
in i t y 11 hEx c ep t io n: e X CO pT. i on ema 11 Add re ss: _einaLilAdd r e fi s J: 

return YES: 

I 

^enc! 


Tor the inii mLifuxJ of NTFxrep[ionHandlerI>elegate, I pass 
it an eniatl address. Tliis Is llic email addres.s where you want 
to receive the exception reports. You need to alltxaie one of 
these objects Mimewiiere in your code. In the sani[>le 
application, I allocate it in +[MyI>tK:umeni initiaiizel. If you run 
t[ie sample application, l^e sure to change the email addre.ss so 
you will receive the emailed reports. 

Next, 1 call two luetliods using the shared default 
NSExr:ept ion Ha ndler object: 

1 iNSExceptionFsndler defuuliExceptiDiiHandlerJ 
setOel©gntc:selfl; 

I [NSKxcC'ptlonllandler defauitExceptionHandlerl 
setExceptlunHandllngHask: NSLogAndflandleEvnryExccpilonMnsk]: 


The call to setDelegate sets lliis instance of 
NTExceptionHandlerOelegate as the NSlixceptionI landler^s 
delegate. Tlte second irall lo setFxceptionHandlirigMask tells 
NSExceptionHandler which exceptkms fm interested in 
handling. I pass NSl/igAndHandleEveryExceptiotiMask to tell ii 
to send me e\'e[y exception. 


There were a few' harniless exceptions ihai were happening 
rretjuenlly in Path Hinder that 1 decided to hlter out. Thai way 
my email lx>x doesn't get full of emails that Fve alreiidy 
detennined to Ix^ OK. The excejyLlon filtering happens in the 
meiluKi slKHiklDisplayException. You may chtx>se to remove or 
modify tliLs code. 

in order for the NTExcept ion Ha ndlerDe legate instance to 
receive the exceptions, it must implement two meihfKis found in 
the informal proifK-ol Icxaled in NSExceptionllandler.h. 

l^lntertace NSObfeet (NSExceptionKflnd 1 o rDelcgutc) 

- (BOOL) except ionHand 1 er: [NSRxc ep L ioii llatidler *) sender 
shouldLogExr.epTion,'(NSExccplion ‘)exceptlon mask: {unsigned 
int)aMask: 

{HOOIdexcepilonilandlej:; (MSExceptlonHandler *)sender 
shnuldilandleException: (NSZxceptlon *)excepi:ion mask: tunslgned 
IntieHask: 

§eTid 

'these are the messages sent by tiic NSExceptionHandier to the 
delegate when an exception occurs. In tire code alxwe yiHi am 
see tlial in llic mclhtKl ext^eptionHandler:shcxjldljogException:, I 
just return YES. This tells ilie NSExccfUicm Ha ndler to log ilie 
exception in the consf)le. In the next method 
excqitionHandlcTisItoukiHandleExceptiommask I call the exxie to 
display the exception to llic user in a window, 'lliis is where the 
magic happens. This window is liandled in l>y the 
NTExccf)ti< mPanelCfmtroller chuss. 

Let's look inside NTExcepiionPanclConrroller to see w'hat 
it does. 

* (id)tnitWithException:{NSExceptlun*)exception 
f?Riai 1 Address: (NSStciugMemaiiAddress: 

I 

self = [super init]: 

_<iisplayFo3it = flNSFont foritWit1iNaBie:®'*Meuacu" size: IB. 0] 
retain] : 

emailAddresft - lemailAddress retain]: 

// kiad ihr riib 

If (l[NSSmidle loadNibNanied:^*NTExceptionPanel* ownerisclf]) 

I 

KSLogt^^Failed to load NTExcopt ionPancI . tilb’'): 

NSieepd; 

1 

else 

t 

(self displayCrashEeport:exception]{ 

// eenUT thr '^linSiw. fstww llic window 

Iwlndow center]: 

[window makeKeyAndOrderFrontinni \ 

\ 

return self: 

I 

The init call loads the nib containing the window, and if 
successful, calls Iself displayCrashRepon:exc:epEionl. The 
window loaded from the nib contains a single N^iTcxtView^ 
displayCrashRepoit's job is to fill that text view with the 
information extracted from the exception. 
NTExceprionPanelControIIer has a simple hcltx.T melhtvtl <'alled 
dusplayTcxt to write a string into the NSlexlView, 
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Here's tlie ctjde: 

- (vold)<]i3playCr3RhR£!pt>rt : (HSExceptlOtt*) exception: 

KSKutflbieArray *args “ [ MSMutableArray array J: 

NSString* appNante = [self applicationNaiEel; 

NSString* stackTracei 

// tlLsphy IrLstraclitJtts 

[self displayTent:appNaKiel i 

[fieif dlspiayText;[NSString stringWitKFormat:§* has 
ancounteired an unexpected error. Please eiBail this report to 
%@ so it can be fixed in the next release,emailAddressJJ; 
[self displayTexti{^''\i Ar”] r 

// display versicJn 

[aelf diaplayTexttapphamoj; 

[self diaplayText:®": "J ; 

[self dlsplayText:[NTUtilities appiiGationVersiun]]; 

[self dlsplayTcxt:e‘Ar\t"l: 

// dbplay OS vcrskHi 

[self displayText: [fflUtilities OSVGrsionll: 

[self di6playText:§*\r\r*J: 

[sel r d i ijplaytext : [exception naaej I: 

[self dlsplayText:f»'*\f\r"l: 

[seif diaplayText:[exception reason]1; 

[seif displ3yText;§'‘\r\r'’]: 

fltackTrace * [[exception userinfo] 
object Fo rK ey:NSS t a c kT ra c eKey1: 

If (ntackTrace) 

I 

// add dll' pnx'tss id 

[args addObjoctlfi" p"l: 

jargB eddObjectj[Juolf applleatlonProceasIDj 
strlngValuelli 

t 

// nnisi iukJ each stack trace as indiv idual argunn-iiis 
NSScanner 'scanner “ [KSScanner 
scannerWlthString?stackTracej: 

NSString’ output; 

NSCharacterSei ‘whitespace = iNSCbaractetSet 
whitespaceCharacterSet ]: 

while (YES) 

* 

if [[scanner 

scanUpToCharactersFroiiiSet :wh i tenpace intzoStrlngi fiiOUtput J) 

[atgs addObject:output]: 

else 

break: 

I 

1 

_atooTai3k “ [ [NTTaskController al locj 
initWitbDelegntetseirl : 

LatosTask rufiTask:NO tool Path iff”/us rVblnyatoe*' 
directory withArgs;args] i 
\ 

I 


Wt* sum by ciisphiying ihc itpplJ^^^bon n:imc anti insrrLKiions 
to the user idling lliciii what has occurred and wliat to do next. 
Next we display the version ol the application, the versic^n of llie 
OS, the exception name, and the exception reason. Next is the 
stack irate. Inside ihe exei>tion userlnlb dictionary is an 
NSString with tlie key NSSrackiraceKey, This siring ltK)ks 
something like this: 

tJx97c^iHtl4 ()xy7dnH2(> OxOlcSHaatJ i)x95()PA:ac 0x931 b^cc 
0x03t5c-51c 0x93<)f3f?hH Ox93l5elfiH 0x9512dc6c 0 x 950 l 102 c Ox950aHc20 
(>x930bldxc Ox931Sfc5B 0xiKJn7f7i tlxtXkXliSd) (1x00003760 Ux(H)0«IKKKJ 


That isn't too useful. Wljal we really need is for those 
numeric addresses to be converted into symbols. 
Fortunately, there ts a built in unix command line Uk} 1 that 
does this called "atos”. Open the Tcnninal and type "man 
atos" for more information. 

In order to run "atos'' we Hrst need convert the string of 
addresses in to an array of intiividual address strings. This is 
used as the parameter to "atosA aios takes this array of 
addresses and converts each one to a human readable 
symbol. In Cocoa this is easily accomplished using an 
NS'fask, In this code I'm using a wrapper around NSTask 
called NSTaskController which makes running an NSTask 
even easier. Basically, it runs the task and sends us the 
output and takes care of all ihe details automatically. Next, 
the code takes the output and adds it to the windows 
NSTextView^ Look at the documentation on NSTask and look 
at the code of NSi ask Controller to see flow this works. It's 
very straightforward. 

Here's some samj:>le output from iiKis. Given the input 
string of: "0x3c7alf(>4 ()x97e54H0^ 0x97dfl82(J OxOleSBitaO 
0x930t9aic 0x93]la3ec Ox9313e54c 0x930f36l:)8 0x93B>el68 
0x9312de6c 0x930c'102c 0x930a8e20 0x930bldac‘ Ox9315fc58 
Ox[K)117f74 OxOO(X)38eO [)x(K)003760 OxCKlOdlOOf)", we get this: 

_SSExceptloiiHand lerExcept i onRa ise t (i n Except i onHand ling) 
+tNSExcGptlon raise:format;J (in Foundation) 

- [NSCFArray objectAtIndex: I tin Foiindetiori) 

- [MyDoeunient except IonlAfstIon: ] (in MyDocument .ob] 
tMyDocuinent.iii: 11 ) 

-[NSApplication sendAcilonstoifrom:] (in AppKit) 

■iNSControl sendAction;to; ] (tn AppKir) 

[NSCell sondActlonFrooi: 1 tin AppKli) 

[JlSCcil trackHouseiinRect :ofView:untilHouJ5etlp;] (in AppKit J 
lltSButtonCen trackHonserinKeetlofViewruntilMouaeUp:] (in 
AppKit) 

■ [KSGotitrol fflooseDown:] (In AppKit) 

-[NStfindow sendEveni:] (in AppRlt) 

-[NSApplicatioo sendEvent:] (In AppKit) 

' [NSAppUcation runj (in AppKit) 

_NHAppIlcationMflin (in AppKit) 

_itiain fin nain.ob) (min.in: 13) 
start (in ExceptlonBarLdlerExampie} 
start tin ExceptlonHandlerSxattple) 

CxOOOOIOOa [in ExccptionHandlcrExample) 

That's a whole lot easier to understand than the string 
of addresses. 

So, we are alniosl done. We have a window which contains 
all the inlonnaiion on tile exception and a stack trace telling us 
exactly w'here the exception occurred. Now all we need to do 
is email this inh>rmalion to the developer. 

Qx-’oa lias a veiy simple interface for .sending an email 
using the class NSMailDelivery. NSMailDelivery Is part of the 
MessageTramew'ork, so you will need to add the 
Mexsiige.framew'ork to your project. I’m using XCode, so to do 
this I go to the "Frojecl" menu and t'iicxjse “Add Frameworks,.." 
and navigate to /System/LiIirary/Frameworks/ and choose 
Message.frumewt >rk. 

- (void)emailAction:(id)sender; 

I 

BOOL iiianSent=N0; 
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NSString ^subject * [NSS^;riag stritigyithFoniiat 
cxc(!ption report", [self applicationNaael J; 

mailSent = [NSHaliDeilvery dfiiivetMessage; [textVl^^a 
atringj subject:subject toi^enailAddress): 

if (JmaiiSctit) 

NSBeep£); // yim may want to ban<lk' thecm>r 

Iwindow close]; 

J 


The email l>uiu>n in the window is set to send the action 
emailAction, In email action 1 construcl a string for the message 
subject anti nse the contents of the NSd'extView as the email 
Ixxly. Sending tlie email retfuires jtisl one line of code: 

mailSent = iHSKaiiDellvery deliverHeeaage:[texTVinw ntrlng] 
subject;subject to: emailAddtesnl; 


SlfMMARY: 

So, ilial'.s all ihcre is too if. Add this ro your application, 
send it out to l>eta testers and get back accurate reports oF 
trouble spots in your code. Ihis debugging tool dex^sn't catch 
all types of hugs. Hiere arc iniiny types prognmuning errors dial 
tkm't tltrow cxccjitions and ilicrcldrc won't l^xf detected by this 
system, hut it is one more powerful tCK>l in your arsenal againsi 
hugs. 
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www.macradius.com 
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Easy to use header and content filtering. Scan incoming messages for sequences of text, 
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Auto Reply 
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COCOA/JAVA 


By Steve Klingspom 


Writing Cocoa Applications in Java 


Mac OS X Ls a great platform for software 
clcvelopmeni. Hie combination of the Mac’s elegant user 
experience, signature design and media tools, breakthroughs 
in moliile computing and UNIX-based tmderpinnings 
continues to lure developers away from <nher platforms. 
Apple has done a great deal of perfoniianee tuning in version 
10.3 ""Paniher,” optimizing the Carbon and Cocoa application 
frameworks while upgrading the underlying Mach kernel and 
BSD environment. Developers have a diverse choice of 
programming languages, from traditional as.sembly, C, and 
C++ to more dynamic language.s like Qbjective-C, Java, 
JavaScript and Python. Apple ships Pandier with "Xcode." its 
integrated development environment, which include.s 
Loniprehensive documentation, sample code and the usual 
compilers and command-line tools. Xcode is an evokuion of 
Project Builder, and adds neat features like code completion, 
fix and continue, predictive compilation, zero link, 
disirilmted builds and a graphiad debugger Developers can 
choose between graplrical tools like Xcode and Metrow^erks 
Code Warrior or more traditional comma nd-Hne text editors 
and utilities. Apple rounds off its UNIX offerings with an XI1 
environment, which makes it extreiiiely attractive to 
devetespers coming fn>in Linux and FreeBSD camps. Apple Is 
now- the lop vendor of high-volume IfNlX systems, and Mac 
users canenjoy a truly remarkafjle, stable, and secure 
operating system, 

Java has surpassed C and C++ as ilie w^orld's most 
popular programming language, and is standard fare at most 
colleges and universities. Sun describes Java as “simple, 
ol)jecl-oriented, distributed, interpreted, robust, secure, 
architecture neutral, ponalde, high-performance, 
multithreaded, and dynamic."' L^evelepers compile Java 
source into platform-independent byre cxKle that executes 
identically across host platforms in a virtual macliine (VM) 
environment. Sun's “Hotspot"’ VM dynamically compiles this 
l)yle code into native object code at runtime, and its 
performance often equals or exceeds liiai of coiri[)ilcd C and 
C++. Apple realized tins wlien moving its WebOl>jects 


application server to Java, as did Netscape when it profiled 
the performance of its Java (“Rhino") and C-based 
(“SeaMonkey") JavaScript engines. The performance 
pniblcms that plagued Java in the early <kys have l>cen 
addressed, and in most cases, the only noticeable tradeoffs 
are slightly longer applicatioa launch times and the memory 
overhead incurred by the VM, Thi,s environment offers an 
additional level of stability and security that C and C++ can’t 
match, protecting a]^]>lica lions from crashing and 
unautlujrized resource access through the use of exceptions 
and a policy-based security modek Java has taken off in the 
server space due to many of these advantages, where stability 
and security are critical. Server-side Java development is 
[Hire joy on Mac OS X, as you can run any of ifie popular 
J21’l'-compliant applicaiion .servers, most ptjpulur relational 
databases, and you can easily deploy on Mac OS X Server or 
any other Enterprise-class UNIX servers wJhle developing on 
your Pow^erBook and listening to iTimes. 

Apple ships Java 2 Standard Edition (J2SE) versions 
1.3.1 and 1.^.1 with Faniher, and these releases are available 
to developers still using Jaguar viii tlie Software Update 
seiAhce. Apple includes a niimljer of notable imprewemenrs 
and innovations in its j2SE implementations, including ilie 
sharing of commonly useci classes ikTo.ss VM insiances, and 
using the Cocoa framework as the basis for its AW'F and 
Ja%^a2D iinpleineniaiions. Tlie net result is arguably the best 
and most tightly integnued implemeriiaiitm of Java 2 available 
on any platform. In addition to the standard tools fre^m Sun, 
Apple includes a “Jar Bundler" utility that assists in generating 
doLible-clickiihle applications from JAR files, and 
“javaBrowser,"' a quic k and useful cla.ss browser that allows 
the browsing <jf Java [)ackage hierarchies and their associated 
class definitions, source code and dcKiimentation withcjul 
switching back and forth beiw^een Xcode and multiple pages 
in a web browser. These two applications live in 
/Developer/Applfcations/Java Tools, and are installed by the 
Xcode installer. Figure 1 depicts JavaBrovvser displaying the 
source c'ode for the java.utikStringTokenizef platform class. 


Steve Klingspom is an independent software developer living in Chkago with his cat Sonya. He hjs an 11 year history^ of working at t'onipanies 
such as Apple. NeLst:aj>e, and Sim. 1 le Is availalile for independent Mac OS X, Java and web cievel(>pment, and am l>e reached at steve@buzzlabsxom. 
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Figure F’ JauaDrowser dispkjying Ibe source code to the 
Stringlbkenizer class. 


C(kx)aJava 

Cocoa is the evolution of the oljjcel-oricntcd application 
fniinewurks developed in the early 90's at NeXT, and was 
iii.striniiental in the transition to Mac OS X at Apple. 
Developers who are interested in wnlitig new applicaiions for 
the Ma<' will probably choose Cocoa over Carbon because of 
its modern, object-oriented nature and aw^ard-winning rapid 
user interface design tool, ‘^Interface Builder/ With Interface 
Buiiden you visually construct your application's user 
interface, dragging, dropping, configuring and tying 
components to “outlets" and "actions” which map directly to 
propcnics and methods implemented in your source code. 
Interface Builder generates "NIB fife** containing frozen 
objects, which are packaged in directories that correspond to 
liie various human languages your application is localized 
into. Organizing NIB files this way together with kK'alized 
program strings gives developers a simple and powerful 
mechanism f(jr providing their applications in many different 
languages and markets simultaneously. 

Cocoa is written in the Objeciive-C language, which 
consists of a small number of extensioas to ANSI C that 
enable object-oriented programming and dynamic runtime 
features. Objective-C is a more elegant and concise language 
than C++, lacks many of its drawbacks and pitfalls, and has 
a unique syntax for defining classes, categories, protocols 
and message paSsSing between ol>jecis. Despite the power 
and simpiicily of this language, C++ won the language war 
in the mid 90's, and Java's popular syntax more closely 
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resembles C++^ while borrowing many of Objective-C's 
features. James Gosling, Java's mastermind^ credits 
Ohjective-C for inspiring many of the language's dynamic 
features, and today uses his PtJwerBook for most of his 
research and development w'ork. While Ohjeefive-C may be 
the language that Apple woiiid like to see developers using, 
it acknowledges Java's popularity and utilizes the “Java 
Bridge” lecfmology the WcbObjects team developed to 
facilitate building fully native Cocoa applications in pure 
Java. While you can continue to develop platform- 
independent java applications using “Swdng" and AWT, only 
Cocoa offers a true Aqua user experienc'e and access to 
platform-specific feaiures that Mac users have come to 
expect. CcK'oa Java is a very attractive option for new' and 
existing developers, leveraging the liesi aspects of these 
technologies without requiring the additional learning curve 
of ma.stering an unfamiliar programming language. You can 
freely mix Objeclive-C and java code in your appl[cations, 
and can design your classes so Co€t>a dependent code is 
separate from more generic code, which can continue to run 
unmodified on other host platforms. 

CRKAIINCi Yom PROjliCl 

To create a new Cocoa Java project, launch Xeexk^ (in 
/Developer/Applications), and select ""New Project..." from the 
“File" menu. Select "CcK'oa java Application," click “Next," and 
tell Xcode the name and location of your new project. If you 
are planning on developing a document'based application 
utilizing the NSDocument class, you may want to select “Cocoa 
Java ITocumeni-hased Application" instead. 


Figure 2 : Using Xcode to create a new QH:oaJatfa fm)j€*cL 

Xctrde will create a new project directory for you based 
on its template for a Cocoa Java application, and will put 


some placehcdder files into this directory, including a 
“MainMcnu.nib" file for editing in Interface Builder, links to 
the AppKit, Cocoa and Foundation framewajrks, and a 
“main.m" Objective-C stub file that is called only to launch 
your application, and is actually optional. Figure 3 show's 
what a new Cocoa Java project window sliould look like. Fhe 
name of your project, of course, will be different from the one 
u,sed in this article. If you are using Project Bulkier on Jaguar, 
things will be arranged differently. A considerable nutni>er of 
articles have been written about Cocoa development in 
Pn>jccl Builder. 



jFigfifie JL' A new Cocoa Jam apldimikm project windo w. 

At this point, you will begin hj follow the usual iterative 
Ctx'oa development patlcrn.s. Mucli has Ixx^n written in 
previous articles and tutorials alxmt this process, which 
generally consists of using Interlace Builder to design classes in 
the “Classes" tiih of your NIfi hie window, specifying instances 
of these classes in the “Instances" tab by dragging or manually 
creating them, and drawling out the connections f^eiween them. 
You then either auto-genenite edit your source code files, 
implementing the various meml>er variables and meihotls 
asstK'ialcd willi the outlets and adions you dehne in the 
“Classes" tab. You should keep all t>f your program strings in a 
text file called “L(jcaHzal)le,sirings," and use 
NSBundle.localizedString to retrieve them instead of hard-coding 
them in your source. You can genersite diffcrenl language 
bundles for other localiz:ilions containing lliis file and any NIB 
files that have lotalizaiion-specific changes, “MainMenu.nib" is 
the default NIB file that Xctxle generates from its Cocoa Java 
project template, and should In:* dtmlile-clicked to launch 
Interfac'e Builder when you are ready to liegtn specifying the 
menus and windows for your application. You c-an brc'iik your 
application's user interface up into multiple NIB files to decrease 
your appliration'.s launcli lime and provide your localizers with 
files tliat are easier to tiianage and edit. 

DlFFEREINCtS FkOM OBJliCllVE-C 

The obvious difference from programming in ObjecUve-C 
is that you will l>e using Java to implement your source files. 
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Tlic CtKoa AppKit and Foundaiion Kit frameworks are 
implemented in the com. apple.cocoa, application and 
com.apple.cocoa.foundation packages. You .should imptm these 
packages in full, or ai least ilie classes from them you plan on 
using, in each of your source tHes that depends on Cocoa. 
You are simply using Cocoa for your user interface and 
platform integration instead of AWT or JFC (\Swing")- 
Everything else more or less remains familiar, and you can use 
any of the tried and true Java platform classes you like mixed 
in w'iih ytHir use of Cocoa. You can add die j>aihs to your 
class, stJurce and documentation files for yoitr application to 
)avaBrt}wser if you wi.sh, and conveniently hrowse them in 
cemjunction with the java and Ccnxm plaifonn classes. You 
can even use “Ant" to build portions or the entirety t>f your 
project, though this will require you to manually WTite a 
"build.xml" file and do a bit of extra work. You will find that 
most (T tlie Cocoa samfjle code on die web and most of tlie 
mailing lists, b(X)ks and other resources listetl at the end of 
this article are written in Objetaive-C, so a rtidimcniary 
understanding of tlic language and its message passing syntax 
will prove useful. Converting lietween Objective-C and Java 
will become second-nature as soon as you gel the liang of its 
syntax peculiadiics, and you wid l>egm to appreciate the 
conventions Apple took in converting the API to java, often 
using familiar interfaces instead of proTtKXils and tlie like. In 
most cases, there is no f)enalLy (or "toir) for subclassing or 
calling back and forth between the two languages across the 
Java Bridge, and Apple's documentation describes cases in 
w'hich you should pay spieciai aLiention to performance or 
memory management issues. 

One key difference lietween Ohjeedve-C and java Cenoa 
is that Apple has not provided Java equivalents for many of the 
I/O, string manipulation and other sucJi classes in the 
Foundation Kit, including NSFiieHandle, NSThread, NSVatue and 
NS Scanner, expecting developers to instead use standard Java 
platform counterparts like javaJo.File, java.Iang.Thread, 
java.Iang.Object and java.util.StnngTokenizer. Use java.Iang.SIring 
instead t)f NSSlring; NSAllribuledString and odicr Cocoa classes 
tlial take strings accept them. Java's network and file I/O 
classe.s are not only familiar u> seasoned Java developers, but 
often offer m<3re elegant solutions than their Objective-C 
counterparts. Java's platform advantages really start to Ix^come 
self-evident when using features like reflection, .serialization, 
and remote method invocation (RMl), not to mention libraries 
like JDBC, wliicli enables a Cocoa devclo]x:r to easily write a 
vendor-neutral relational database application with a native 
Coc'oa user experience in an ahernoon. Any of the countless 
Java packages and libraries available c'an lie leveraged by your 
Cocoa Java applications, saving you time and allowing you to 
concentrate on implementing application-specific funclionaiily. 
This truly powerful combination of teclinologies .should not lx; 
overlooked by anyone considering using Objective-C for their 
next killer Cocoa app. 
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Mixing Java and Cocoa 

For llic j>urfxxses of lIuh arlido, wtr will t>e exiimining 
some of the code from '‘Aquataxx/' a Cocoa Java 
implementation of the classic arcade strategy game, “Ataxx,"’ 
shown in Figure 4. Aquataxx is a Lomprehensive example of 
using Cocoa feature's like baished metal windows, drawers, 
sheets, bouncing Dock icons, text editing, fab views, user 
defaulLs, localized strings, drag and drop, sound, animation 
and drawing in custom NSView subclasses. In addition, it 
sports a game engine with impressive Al, networked game 
play and messaging, a standalone network **roster server" for 
finding other online players, and some advanced threading 
techniques, all written in portable, platforni-agnostic Java. 
The result is a portable implementation of Ataxx with a 
challenging computer player, a rich, tliemable C(K’oa user 
experience, network pkiy and chat, and more. Writing the 
same game in Objective-C would have taken longer than the 
two weeks it look lo write A<|ualaxx, 


Listing li 

A simple QKX3a"aelion" mctliiTtl, Imked from Uie NIB file in Inierfaee Builder. 

/•' 

Shows ihc alxjut sheet 
©param sender ilje sender ol'tlie meiisaj^t 
’V 

public void sho^AboutShcer(Object sender) 

{ 

/* Set rhe version string, If need be 7 
KSTextField versionField = 

(NSTextField)mAboutPanel.contantViewD, 
vievWithTag(l): 

String, versionStting ” versionField.stringVa1ue(}; 
if (verelonStrlng. 1 ndexOf (’■ ( OP') > 1) 

I 

StringBuffer buffy = new 

StriugBuffertAtaxxApplication.AFPLICATION.VERSION): 
buffy.append£" - Java 

buffy.append(Systeni.getPraperty("Java,version^)); 
versiemString ■ MessageForinat.formatfversionString, 
new Objectfl t buffy.toString{) I); 

VC rs1onFiold.setStr1n gVa1ue(versions tring); 



Figure 4: Acinataxx, Cocm jam game im%l 
as afi example in ibis article. 


Listing 1 depicts using Cocoa anti Java f)laLform classes 
together to implemeni rhe action method that is invoked by the 
"Alx)uL AtjuaUixx” ilem in ihe ‘‘Aquataxx" application menu. 
Note that the method is public and a regular java.Iang.Object is 
used for the sender parameter, We splice the Java version frotn 
java.lang.Systam into the fmsion NSTextField and display the 
game'.s alxjut sheet. 


/* simw (hr skci 7 

NSApplication.sharedAppiication().beftinSheet ( 
mAboutpanel. mGameWindow. this. null, null); 
I 


MriviORY Management and Thread Safety 

In most cases, you will not have to explicitly worry alx>ut 
memoiy management in your Cocoa Java applicaiions. The 
usual warnings regarding hanging onto references and what not 
still apply, and Apple has a document that is referenced at the 
end of this article iliat explains ihc exceptions to these general 
rules. In some cases, lo get around coiriplicated interactions 
between Cocoa and Java objects, you will need to wrxip objects 
in an NSArray; in others, you may have to catch possible 
NS Exceptions rliai can he tlirown hy Cocoa object consrructor.s. 
For rhe niosT part, the tricky retain and release memory 
manageitieni conveniit)ns used in Object ive-C can lx? avoided; 
another one of Java's advantages improves llie Cocoa 
development experience! 

Java developers are used to satisfying ilic needs of most 
modern applications, especially those that use network I/O, 
with multiple threads. Java encourages the use of 
muliithreading, and Java thread.s tjava. 1 ang.Thread) on Mac OS 
X are implejnented as native Mach llireuds, so they have 
excellent perforjiiance. One of the inherent pitfalls of 
multithreaded pnigrartitiiing is 1 bread safety, and many aspects 
of the Cocoa Ira me works are not yet guaranteed tt> lie thread 
safe, meaning you cannot safely cal! many aspects of Cocoa, 
including ytjtir user interface, from background threatis such 
as one that blocks on incoming network I/O. Since network 
socket I/O blocks in J2SE 1,3d- and holding up the main 
thread in which many aspects of Cocoa inrltidirig your u.ser 
interface run in can result in unacceptahle performance, a 
mechanism is needed to enable background threads to tell the 
main thread to execute code that interacts with Cocoa. 
NSObject in Ohjective-C has a method, 
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performSelectorInMainThread, but un fortunately this 
lunctionaliiy is not available in Cocoa Java. To gel arountl 
this, the most popular strategy is to subclass NS Application untl 
implement sendEvent to handle application-defined events that 
a>rresfK>nd to blocks of axle that need to be called in the 
main thread. Code that is called from your sendEvent 
implementation is guaranteed rim in the main thread. Tailing 
to observe the fact that many aspects of Ccx'oa are not thread 
safe will result in unexpected, random crashes inni 
exceptions) that can be hard to reproduce and debug and 
appear to be in (aicoa's Objective-C ctxle. These types of 
crash logs can be confusing to developers programming in 
pure Java, yet can often help in tracking down sections of 
code that should be run in the main thread. Listing 2 is the 
full source for AtaxxApplication, the custom NSAppiication 
subclass used in Aquataxx to handle events posted by 
background threads. Listing 3 depicts an example of posting 
such an event. The full source for Aquataxx is referenced at 
the end of this article, and can be examined for further 
examples of using this technique to assure your application 
plays by proper threading rules. 

Listing 2; 

AUJtxAppliciitiofvan NSApplkaMon i^iihcb^s ihai handits applicaiion-dcfincd events. 

/* Atu.'LTLApplicat ion. java 7 

import cojn.apple*cocoa»fDundatIon.; 
import com.appla.cocoa.application.*: 

r 

A NSAppiication suhiia.'is lo add die abiliw u> rtTipimd to applkaiion^lctlnc'd o^’ent.N, 

public class AtaxxApplication 
extends NSAppiication 
I 

r* Application version stfinw *7 

puhn<' static ftnal Siring APPLTCATI0N_VERS10N - 

r Applic aiN>n-<k“fmctl event types */ 

protected static iinal short NEW_HATCH_EVENT = 0: 
protected static final short SCROLL_CONVERSATION_EVENT = !■ 
protected static final short CONFIRM CONNECTION.EVENT “ 2i 
protected static final short UPDATE ROSTER EVENT ^ 1; 
protected static final short 1KC0MING_0R0PPKD_,KVRNT - 4: 

r 

Ovt^rridden to respond to rustom events, 
i^param event tht: i-vent hring processed, 

**/ 

public void sendEvent{NSEvent event) 
f 

/* Only wt»rry alxiui utjplloiioti-defijieij m-nts 7 
if (event.typeC) NSEvent.AppllcatlonDefined) 

I 

switch (event ♦auhtypeO) 

[ 

/* f'ft-ne :i new nttitelt 7 

case NEW_rtATCU_EVENTr 

1 

At axxCo ntroller.sha r edCont r ol1e r() . 
startNewMatch(event.data t()* 
event.data2CJ): 
breakt 

1 

r HcroU the conversation view 7 

case SCROLL^CONVERSATION.EVENTr 

{ 

AtaxxController.sharedControIIer(}. 
scrollConversaT ionViewO : 


break; 

I 

/* Confirm a conneetion rcqiicst 7 

case CONFTRM_CONNECTiaN_EVENT; 

I 

AtaxxCont roller. sha redControlier (}. 

confinnConnectionRequestt); 
break; 

1 

r Update roster data .sfjurce V 

case UPDATE ROSTFR.EVRNT: 

1 

AlaxjtCunt roller*sharedController {). 

updateRosterUataUourceO ; 
break: 
f 

r Lkwic die connecLiem rLV|iie?ii sheet 7 

case TNGOMIKG_DR0PPED_EVKNT; 

I 

AtaxxCon t rolter,sha redCont roller C)* 
closeAnySheet(null); 
break: 

J 

I 

else 

I 

super.sendEvent(event); 

I 

I 

I 


Listing 3; 

A wmp|XT meth<jd that p<isis un application-tlefintil event. 

r 

hiSLs an applic'ation^lifjntd event to I he eum'nt application. 

pa ram code the event code 
#p:iram datal the first parameler 
e^parami duui2 Uic second |>aniiiieier 
^jpararn from post to the front of die queue? 

public void postAppllcnUoJiDefinedKvent (short code* 

Int datal. 
int datal, 
boolean front) 

I 

NSEvent event ^ 

NSEvent,o t h e rEve nt t NSEvent.A p p1ica tionDe finod. 

new MSPoiattO. D). 0* System.currentTinieKilUs() / 
1000 * 0 * 0 , 

null. code, d^tal. daral): 

NSApplleai ton*sharcdAppllcatlon(1.puslEvent(event* front); 

! 


IMPI.EMF.NTING CtJSTOM VlF.WS 
One of the more rewjtrcling a,speU.s of Ctxoa programming 
is implementing your own NSView suixliis,ses. NSView is the 
b;i.se class in the (^x'oa user interface class hierarcliy, anti all t>f 
(lie user rnterfac'e components you see and inrenict with 
inevitably inlierit from it. If i>ne of Apple's standard views dtx^ 
not suit the ty|^ of data or interaction you are trying to 
represent, as is the aist: with the game Ixiard and player score 
views in Aquata.\x, you sturnld implement a ciLStom NSView 
subclass. You .suIkUiss NSView in the “Classes” utl> of your NIB 
file window In Interface Builder, and create a corresponding 
Java source file just as you w'ould if you were using Ohjeeiive- 
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C, listitig 4 Is the complete source code for AtaxxScoreView, 
custom view that draws lx)th playeni' names and ,scorcs and 
liighlighls the active player witli an etched apjsearance diat looks 
similar to iTunes. I'or a more comprehensive and exciting 
example of a custom view that handles events and uses 
optimized drawing and tlrag and drop, take a look at the source 
for AtaxxView, which draws the game lx)ard and is fotmd in rite 
full source code distribution. Cocoa user interface programming 
is a lot more fun, inluitive, and rewarding liian using “Swlngr 


Listing 4: 

'rUc camplcrc sourt' ftjr AfaxxScoreVk'w, a c:iisTf>m NSView HtibtIsLss, 

r AuxxScort View, java */ 

import cQTn.iipplci^ cocoa* found at ion** : 
iropo rt com * a pple * cocoa * application * * t 

r 

A t'u^Tom NSVk'w ,^iilxla.s*s Thai dL^pfay^ an etdied 
nttialJk M.ti[ti>oanJ for iwu players, and Jiightighf^ 
iIk pLaycr wlui^ turn it b. 

”/ 

public class AtaxxScoraVlcu 
eirtendfl KSView 

I 

/* Tht^ colors for drawing the sc<jrehoanl ’/ 

public static final NSColot FOREGROUND_COLOR * 

NSColor .colorWlthCalibratedkGB{. l^Of, *ZOf* *20f, l,Of); 
public static final NSColor BACKGHOUND_COLOR = 
KSColor*whitsColctr() ; 

public static final NSColor FOIlEGROUm}_UP_COLOK = 
NSColor*bIackGolor() ; 

public static final NSColor BACKGROimB_UP COLOR = 

NSColor * grayColor()] 

/* Htc (four) aurihulcd sa}R firings ((back, front) * 2) V 

private NSHutableAttributedString mScoreStrlngs [] = null; 

r 

Cxmsimcmr 

^param frame the frame retiangk 

“/ 

public AtaxxScoreVienENSRect frame] 

I 

super(frame); 

mScoreStringa “ new NSNutableAttributedString[4]; 

) 

r 

Tells the window server tb;U we arc not opaque (we ate transpateni). 

(^returns falsi*, as we arc rransparcnt, 

"/ 

public boolean isOpaqueO 

( 

return false: 

) 

Oraws the view 

® pa ram rccr tlir uptbiif rectangle 

“/ 

public void drawRect(NSRect rect) 
f 

if CmSeoreStrings I* null) 
t 

KSHutableRect stencil = new NSMutableRect(bounds()): 

stenciX*inBetRect{0*5f* l*Of)' 

stencil.neiOrIgInfnew NSPoint(I *0f. Q.Of)); 

NSGraphlcs*drawAttrlbutedSiring(mScoreS i r ingsl€l, 
stencil): 

NSCrapbics * d rawAtt ributedSt ring(mScoreS t rings(2J, 
stencil): 

stencil*setOrigin(new NSFointtO.Of, l*Of)); 
NSGrapbice*dravAttributedStcing{raScoreStriTigs(Ij * 
stencil); 

NSGraph tes* d ravAttrihutedSt ring(mScoreStrings[3], 
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stencil)^ 

I 

I 

r 

Creates the i atTribiited score string, based un 
ibc ciinent score strings and pla^vr that is up. 

^parnm player 1 rhe siring for the first pfaycr 
^|wvtm playeri the string for the second player 
@parani up die player tliai is up (hiliglited) 

(0 = none. 1 = plav er 1,2- player 2) 

"/ 

public synchronized vn!d updateCString playcrl, 

String player2t 
int up) 

r J'or convenience in looping through die siiiiigs 7 
String strings[J * I playerl* piayerl, player2, piayfir2 h 
NSMutableArtributedString newStrlngsf] - 
nRv USHutableAttrlbutedString[4l; 

for (ini i “0: i <4; i 2) 

[ 

/* Ca^te the pair tif aitrihuied strings (foaganind and hackgroiind) V 
newStringsliJ = 

new NSHutableAttributedSttingfstringsfil): 
newStringsri + 1] - 

new NSHuT 0 bloAttributedSrring(fltrlngs[i + 1]): 

t Cfraie a ange for ihe string pair 7 

NSRnnge range “ new NSRangefO, stritigstil *length() >: 

r Sel dte text alignment 7 

NSMutableParagraphStyle paragraphStyle “ 
new NSHutableParagraphStylcC); 
paragraphStyle*setAllgniaent{ (1 < 2) ? 

NSText .LeftTexrAl ignnsont : 

HSTeat .HlgluTeJt I Alignment); 
news l rings (i] *addAttribviteitiJlange t 

NSAttributedString,ParagraphStyieAttributeName. 
patagraphStyieK range): 
newStrings[i + 1].addAttrlhutelnRangeC 

NSAttributedString*ParagraphStyleAttributeName, 
paragraphStyle, range); 

r Set die font to the system font, size 10 (Jotalization?) 7 

NSFcmt font = fJSFont .aysteitFoncOfSlzedO); 
newStrings |1J .addAttributeInRangeC 
NSAttributedStritii. FontAttrihuteMarae, 
font. range); 

newStrlngsfi + 1],addAttributeInRange( 

WSAt t rib u t e d S t rin g.FontAtt r1bu t e Name, 
font, range); 

r Sri rhe frin^gnmnil atui background colors V 

RSColor foregroundColor = FOREGROUND_COLOR; 

NSColor baekgroundColor = EACKGROUNB_COLOR; 
if t(i < 2 up -- 1) II 
{i > I up 2)) 

( 

foregroundColor = F0REGR01lriD_UP_GObgR; 
backgroundColor = BACKGROUND^UF^COLQR; 

1 

nowS1rings[11,addAt t ributeinRange( 

NSAttrlbutedString,ForegroundColorAttributeNante* 
backgrotindColor, range); 
newStringali ^ 1].addAttributelnRangef 

NSAtt ributedSt ring,ForegroundCoIn rAttrlbuteNanp, 
foregroundColor, range): 

/* FI K up 1 he aiifibuies, whatever Thai ik>es 7 

newSt ringa li]. fiKALtributeslnRangeCrange): 
ncwSitingsfi ^ 1] ,fixAttributesltiEange(rangeJ; 

r Set ilie actual aitributeil score strings 7 

mScoreStringsIi] - uewStrings [J]; 
mScoroStringsIl + 1] ^ newStrings !i + U : 

/* Retiraw ihe view' V 
display!); 

1 

1 


Coist:uJsu)N 

Java is an exeeQent choice for devebping Cocoa 
applications. If yon are a Java prognmimer, are new to Cocoa, 
or are not interested in learning Objettive-C, you should give 
Cocoa Java a try. The popularity of the language and the sliecr 
qimntit>^ of third-part>' Ubmries and tools provide Java 
programmers willi an iinprusvsive array of pre-engineered 
solutions over those available in Objective-C. Apple continues 
to provide Java interfaces to the new features it adds to Coco;i. 
Its lime for devclt)ix.TS to take better advantage of tliis 
technology and provide Apple with tile feedback they need to 
make Cocoa Java even Ix'ften Itie end result is more great 
applications for Mac OS X. 

Resources 

The following resources will lielp you get staned tn learning 
ak>ut Cocoa Java programming. Sun has a general Java 
language tutorial, Apple has a CtKoa Java tuiorial, and there arc 
stwerai Siimple appliratioas installed with Xcode diat w^ill prove 
to l>e gtxxJ references. The Aquataxx game distribution and full 
source cxxle referenced in this article is available, ;ijid Aj^ple and 
Hie Omni Group have gfxxl Cocoa development mailing lists 
that can lie browsed and sorclial at http://cocoa.mamasam.eom. If 
you have questions that yiiu cannot find the answers to, or 
would like to dtsc'uss CcK'oa Java programming in general, you 
can contacl the author at Steve@buzzlabs.com. 

Ac[ualaxx game distribution and Cocoa Java source code 

http://buzzJabsxom/aquataxx/ 

I’he Java 'rutorial 

http://java,synxom/(locs/books/tutorial/ 

l>eveloping Ccxoa Java Applications: A Tutorial 
http://developer,apple,co[TVdoaimentation/Cc<oa/Coriceptual/javaTutorial/ 

Apple Cocoit Java Examples (Xende): BlastApp, Sketeh, 
SimpleTbnlbar and 'textEdit 
file:///Developer/ExarTiples/Java/AppKit/ 

Java/Objective-C Language integration: Java Memory 
Managemem 

http://developer,apple.com/docunientation/Cocoa/Coaceptual/Language 

Integration/Concepts/memory.htm! 

The Objective-C Prograitaiting Language (Xcode) 

file:///Developer/Doajmentalion/Coc(>a/Conceptual/Objed]veC7index.html 

Cocoa-Dev (Apple) and MacOSX-Dev (Omni Group) mailing 
list arcliives 

http:i/cocoa.mamasam.com/ 
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^Thinkfree^ 


ThirikfreeOffice 

compatible with MICROSOFT WORD, EXCEL AND POWERPOINT 
WORDPROCESSOR • SPREADSHEET • PRESENTATION GRAPHICS 

The Affordable Office Alternative! 



iacworiil 

!W»I 


-Thlnklrw is a 
twst-ot-braed 
that wilt exceed your 
expectations,*' 

— Jeff9ry SotlenitY 


MaC^^icJdcl RATED 

00000 


GREAT 


“ThinWree Office is the 
next beat thing and 
ttren some.'* 

Deborah Shadovitz 


■'Thinkfree Office Is an 
fnlSlCHOMcT impr^essive sttempl to 
crack the si^rningly 
impenelrabk} 
productivity market,^ 

— Citfis Ward 
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Th ree High-Performance Applications 


Thinkfree Write 

Thinkffee Write is a powerful word processtr^g appltcofion 
rtial ertobles you to create rich, professionol quality 
documents and Web pages. You can insert tables, 
images, and clipart, or even apply custom layouts to 
your document...then effortlessly proofread your work 
with the easy-to-use spelling and outo-correction features. 

Thinkfree Calc 

Thinkfree Calc ts a full-featured, easy-to-use spreadsheet 
opplicotion that con easily tackle the most complex 
onolyticol tosks with over 40 charts and 300 function 
capabilities. Thinkfree Cole opens, edits, and saves 
directly into the Microsoft Excel (.xls) formot, so users 
can seamlessly share documents and collaborate with 
Microsoft Office users. 

Thinkfree Show 

Thinkfree Show enables you to create high-impact 
presentations including animotion effects, drawings, 
images, diport, and other graphic features. Thinkfree 
Show opens, edits and saves directly into the Microsoft 
PowerPoint (.ppt) format. 

Cyberd rive Plus 

A free, one-year subscripHon to CyberdrivePlos is also 

included. CyberdrivePlus provides you with secure, 

Internet file storoge and free online software upgrades! 


ONLY 






Thinkfrw and Thinkfree Office ura Irodemarks erf Thirtldree Corporoliofii, All olher frtadeifiarkj ond/or regi^red IrodBrnarks arts properties of their respeclive owners. 
















































SECTION 7 


By Rich Morin 

ESR, etc. 


A multiplex review of a singular 
individuaL. 

Brie S. Raymond (uka ESH) is best known for his 
activities in support of Open Source software. Several years 
ago, he convinced a group of key developers to adopt die 
term as a less-arnhiguous and more marketable'’ 
replacement for the existing term, “free software”. 

Note: Tile term “Open Source” was actually coined by 
Christine Peterson (President of the Foresight Institute; 
hnp://wvvw.foresight,org). Abo, the term “Free Softw-are" still has 
Us adlierenis; see http://www,fsforg/philosophy. 

Since that time, Eric has written extensively on topics 
related to Open Source software. His essay “The Cathedral 
and the Bazaar” is probably the best known of these essays, 
hut the others are also worth reading. See The Cathedral and 
the Bazaar: Mustngs on Unix and Open Source by an 
Accidental Revolutionary” (O'Reilly; htlp://www.oreillycomt. 

Two of Eric's essays. “A Brief History of I lackerdom” and 
"'I he Revenge of llie Hackers” a[)[K“ar in the excellent collection 
“Opon Sources: Voices IVuni the 0[)en Source Revolution” 
(Diliona, et al; O Reilly), if you w^ant to understand hacker 
culture and the Open Source movement, bodi of these O'Reilly 
b<K)ks wtHild lx- excellent starting points. 

Eric lias also l>een busy on the oiganizaitiiHial and legal 
skies of (.)(x*n Source. He is President of the Bfvard of Directors 
of die Open Source Institute (http://www.opensource.org). He has 
also published (and pulilicizetl) a niimi>er of internal Microsoft 
dtK'uments, weighed in on relevant kiw.suils (e.g., the SCO 
unpleiLsaniness), etc. 

OriJliK PlfBUCATlON.S 

Eric writes exteasjvely, aweiing a wide mnge of topics. Ills 
lunne page (http://catb.org/-esf) has links to essays on 
unthropt)logy, economics, jKiliiics, science fiction, and many other 
areas. Even if you tlon't agrex* with Eric's opinions, yt>u should 
find his w'ritings to be interesting and thought-provoking. 

A.S Che long-standing steward of the Jargon File 
(http://www.jafgon.org; also available as Tie New Hacker's 


Diciionary” from MIT Press, http://mitpress,mit.com), Eric acts as an 
editor, lexicognifiher, historian, and (occasionally) anthropologist. 
Itie definitioas tend to Ix" far more interesting and enjtiyable than 
one might expect from a conventional “diciionary”. 

The Art of Unix Pkogramminc; 

Over the past five years, Eric has been working on a 
distillation of die lessons that Unix has to offer the 
programming community. Taking his own advice C*Many 
eyes make all bugs sballow.") seriously, he brought in a 
number tif Unix wizartLs a.H atlvisors, As a result, Tie Art of 
Unix Programming” (Addison-Wesley; http://www.aw.com) is 
enjoyable, educational, and for the most part, authoritative. 

Although the bonk ckxtsn't address Mac OS X, in particubr, 
it has quite a bit to say about the BSD side of the operating 
system. For instance, ii talks at length d\x)u{ die Unix practice of 
encoding informatifin in text files. OSX, with sometldng like 
!t)()K text files, certainly seems lo have adopted this idea. 

It also discusses pofiular idc*iis such as ohject-oriented 
prognmiming, threads, giving reasons why these* rnighl not lx? 
the ixfst possible approach in all circiim.stances. All told, this 
IxM^k is the Ix'St introduction 1 can suggest tor a Mac OS 
firognmimer who wants to undei-.stand the BSD (read, Unix) side 
of Mac OS X. 

More can be less 

True lo Unix tradition, Eric extols the lx?nefits of having 
many different tools. Again, OSX is rigfil there, providing a 
plellioni of programming languages and other useful uliiities, I 
wonder, however, whether OSX (and the Open Source 
community, in general) may not lie suffering from an 
embarrassment of riche.s. 

In fierusing leads for programming jiositions, many of us 
have noted die extreme diversity of skills that may l>e demanded 
IVir a single position. ApplioniLs iue exjK^cted lo have several 
years tif experience in each of several languages and tools. 
(Then, it is hard to conceive reasons for using these languages 
and tools in a single pi eject. 

Ignoring (he discouraging effect of such postings on 
prospective applicants, let's consider how the company 


Rich Morin has Ix'cn using computers since 1970, Unix sincx" 1983, and Mac-based Unix since 1986 (wiien lie helped Apple create ATIX 1.0). When 
he Isn’t writing this column. KU h nins Frime 'time Freeware (www.ptf.com), a publislier of tx>oks and CD-ROMs for the Free and Open Souiee software 
community. tk?el free tt> write lo Rich at rdm@ptl.C0m, 
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managed to get into the position of needing tUis son of 
polymath. .Speculating, 1 propi^se that ihc company once had 
a numl^er of programiucrs, each developing part of a 
ccmtpicx sysieiiu Each programmer chose the "right tool for 
the job”, in true Lfnix fashion. 

'rhe company now lias far fewer programming positions, 
hut it still needs to niaintain a polyglot mass of sofiware. 
Their job postings are totally unrealistic - no single 
programmer can have extensive skills in more than a few 
areas - but they are merely a symptom of a larger problem. 

OSX has similar historical baggage. If you look in /etc, 
you will find numerous control files. Most of these are "flat 
files”, employing newlines to separate record.s and some 
form of delimiter (e.g., colons or "white space") lo sef)araie 
fields, llnfortiinately, the exact format varies, so programs 
(and adminisiralors) must "understand” ciifferem syntax For 
each file. 

The log files are in even worse shape. They may be 
written by mulliple programs, so the formal can vary from 
entry to entry. Becau.se the entries were written for liuman 
consumption, they often pnivide no unambiguous way for a 
program to distinguish fields, This is a serious problem; if log 
files are too big for humans to read, and ton messy for 
programs to read, exactly what purpose are they serving? 

Moving on to OSX's “plist” files, we find two distinct 
formats in evidence. One, inherited from NeXT, uses a C-like 
syntax. 'I'he other, .strongly encouraged by Apple's current 
dcKiimentation, is based on XML. Using the appropriate 
frameworks, an Apple programmer can read eilluT file. An 
administrator, however, may need to be familiar with both. 

Although f'm a big fan of Yj\ML (YAML Ain't Markup 
Unguagc; http://www.yaml.org), I sometimes wonder if 1 might 
l>e making some programmer or adminisirator'.s life more 
difficult, by imroducing yet another data format. Sigh. 


Brogramming languages are another area of ccmcem. 
OSX IS built out of C, C++, Object!ve-C, and a smattering of 
scripting languages. C Ls used lor the "Core OS" (kerneh BSD 
lil)raries and programs), hut C++ is used for the lOKit and 
most device drivers. Objective-C is u.sed for the higher-level 
frameworks and applications. Finally, the scripting language.s 
are used for all sorts of administrative glue. 

Fortunately, few programmers write program.s in all 
these areas. If youVe writing GUI-based apps, youTe unlikely 
to be writing device drivers at the same time. If youVe a 
serious scripter, you may never look at any C (etc) code. 
Unless, as I am, youTe using Perl, Python, or Ruby to build 
Cocoa-based apps. 

For all my misgivings, however, 1 wouldn't want to be 
restricted to a single data formal or programming language, 
XML is powerful and very "buzzword-compliimi”, but it's al.so 
verbose and a poor match for a.s,soLiaiive arrays. Ol>jective-C 
is a tidy integration of 00 into the base C language, but its 
tiiemory management seems a hit awkward to my Perl- 
accustomed eyes. 

Ockham's Razor (“Pluralitas Non Est Ponenda Sine 
Necessitate.") transliterates to "Plurality shoulci not be 
posited without necessity", reminrfing .scientists to remain 
parsimonious in imagining new mechanisms. It is also 
translated, however, as "Entities are not to be multiplied 
l>eyond necessity” and even "Keep It Simple, Stupid". 

Jn short, our challenge as developers is to decide how to 
at'liieve simplicity (once we have decided what "simplicity" 
is, in a given context while retaining the power and 
flexibility that our mixed programming heritage provides. 

Erics latest offering, like many of his earlier wmlings, 
helps to show us the way... 






t 





Now serving Cocoa 
just the way you want it. 

Tratnirig ter Mac OS X doesn’t have to be thd ^rrie old fla'^'or. 
Reserve your seat in a class at our scenic lodge location, 
or have experts come to you ter Extreme Mentoring. 
Two weeks of on-site instruction and collaboration, 
customized to the requirements of your project. 
Book now for 2003. See why we’re different. 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 

The Matrix Revolutions 


Handling Movie File Operations with 
Revolution 


Introduction 

In the previous two QuickTime TootkU urtieles (in MacTecb, 
Sep!cnil>er and (XTol^er 2(X)3), we've taken a look ai Revolution, 
d rapid application development tCK)l piiblislied hy Runtime 
Revolution Ltd. So htr, weVe develupc'd a fairly complete 
application — called RiinRevVeez — that can oj>en and display 
QuickTime movies. Our application also supports basic editing 
opertuions on tliose movies (cut, copy, paste, and so forth). In 
this article, well finish up our tnvestigaiion of Revoliuion by 
iinplemeniing the basic file-handling operations. We'll see how 
to keep track of wlteihera movie has been edited, how to adjust 
the items in the File menu accordingly, and how to save an 
edited movie into a new file. And well see how, when the user 
decides to quit RunRevVeez, to iterate through ail open movie 
windows and give the user the chance to save or tlist’ard any 
unsaved changes to those movies. Figure 1 .shows the File menu 
of RunRevVee/, when at leas* <5ne movie window is open and the 
movie in the Irontmost window has Ix'cn edital. 


^ RunRevVeez 

EQ Edit 

Movie Help 


New 

«N ^ 


open... 

XO ! 


Close 

sew j 


Save 

ses 


Save As... 



/: We File menu o/RunRevVeez 

It's w^orth noting that these techniques miglit lx of interest to 
any Revoluikm developers who need to create documents and 
store the iiiFonnation in them, as tliis issue does not appear to 
lie well documented. 


Toward the end of this anicle, we’ll take a Icxjk at Ixiilding 
and packaging RunRevVeez for distribution to users. The main 
hurdle here involves comfiining into a single item the application 
built l>y Revolution and the external plug-in module built by 
Project Builder Tliis isn’t terribly difficult, but once again it’s not 
well dcK'umented, So it’s woitli touching on the topic, 

A few final notes Ix^fore we liegin. First, 1 have upgraded my 
development environment to Revt^luiion version 2,1, which is the 
current version as of ilte lime Fm writing this. (The two previous 
an ides used version 2.0.2.) So you may notice some differences 
in tile interface if youVe still using an earlier version. 1 
encountered no problems when upgrading to version 2.1; tlie 
existing version 2.0.2 lUinRevVeez project could lx opened and 
modified using version 2,1, Moreover, by the time this article 
makes it to pies,s, tlie current version will be at least 2.1.1 (more 
on that later). 1he folks at Runtime Revolution seem to lx 
commilled to making their Mac OS X product as solid arul stable 
as they can, and improved versions seem to be appearing fairly 
often, 'Phis is a good thing. 

Also, you may notice that the movie windows and dialog 
iKixes have a slightly different appejimnce from those in the two 
previous urticies. 'fliar's Ixcause tlie screen sliots for this anicle 
were taken with RunRevVeez running on Mae OS X version 10.3 
(also known as “Panther’*)- 1 encountered no problems running 
Revolution or the aj)pitcations it creates untier Panther. 'Phis also 
is a gofxl thing. 

FlU: MA.NlPl)IAn()N 

So our goal right now is to finisli RunRevVeez by 
implementing the baslt^ file-handling openiiioas (aside from the 
Open menu item, which we covered in the earlier arrides). in 
panicular, we want to lx able to track changes to a movie and 
allow^ tile user to save tho.se changes. In the previous article, 
you 11 recall, we saw how to implement the standard editing 
operations. To do this, we tieeded tt> use an external code 
[Tioduie that called QuickTime’s movie controller editing APIs 
{for instance, MCCut and MCPaste). We also defined a custom 
property for each movie window {which we called 


Tim Mofiroe Is a member of the QuickTime engineering team at Apple, You can contact him at monroe@madech.com, Tlie views expressed liere are 
not necessarUy siiared by his employer. 
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movieChanged) lo keep track of whether the movie in that 
window has been edited. 

Knahling and Disabling the File Menu Items 

We can use that custom pmperty to help us enable and 
disable the items in the File menu according to llie state of the 
movie in llie frontmosl window. We want the New and Open 
menu itetns to Ixf enabled always, and we want the Close anti 
"Save As..." menu items to lie enabled only if tlie fn>ntrnoLSt 
window is a movie windtjw. Finally, we want the Save menu 
item to lie enaliletl only tf the fronrmost window is a movie 
window that has been changed since ii was Iasi opened t>r 
saved. Easting 1 shows the code we add to tlK" mouseDown 
handler of tlie main menu item group. 

Listing 1: Adjusting the File menu 

on iiDusellowa 

eonetant kNevltemlndex “ ! 
constant kOpanltemIndex == 2 
constant kCloseltenlndex ~ 3 
cDTistant isSaveltemIndex “ 5 
constant kSaveAsItoDindox ^ 6 

put first line of the openStacks Into theXopStack 
put exists[pluyor "MoviePlayef" of stack theTopStack) \ 
into gotFlayer 

enable oenulcem kNewItemitidex o£ menu. "Flic" 
enable menultera kOpenltemlndex of raenu "File* 

dlfisbln menultem kCloseltemIndex of menu "File" 
disable inenuTTem kSav(>TteraTndex of menu "File" 
disable menuItem kSavoAsTtemTndex of menu "File" 

if gotPlayer then 

enable menultera kCloseIteraIndex of menu "File* 
enable menultein kSaveAsltemlndex of menu "File" 

if the movieChanged of stack theTopStack is true then 
enable menuItem kSaveltemlndex of menu ■File* 
end if 

end if 

end mouseBown 

lliere’s nothing here that wc haven't seen Ix^forc, cxccj>t 
the use of die constant command to define some symbolic 
constants, Tliis of course makes our code more readabitj and (in 
thetJry) more maintainable. 

Creating a New Movie 

In the previous two articles, we saw how to liandlc the 
Open command in the File menu to oi>en an existing movie file 
and to display the movie it contains in a window on the serreen. 
Revolution provides easy access to the standard file-ofMjning 
dialog box, and ii returns die full pailiname of a selected movie 
file, which we can assign to the movie player object. 

But how wouicl we handle the New menu item, which 
should open a new movie window tiiat contains an empty 
movie not associated with any existing fHe? Here things get a bit 
tricky. We can open an empty document window and leave die 
filename of the player object in that window^ set to the empty 
siring But in tJiat case the movieControllerlD property of the 
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player object will lie 0, and this renders the new player object 
pretty much useless. We won’t he able to paste any movie data 
OIL ov copitxJ fn>m siime other movie into tr (which is itsually 
what we want to do with empty movies). 

One solution to this problem would be to create a new 
empty movie and an associated movie controller ourselves (in 
our QuickTime external module, of course) and then iissign the 
movie controller ID to the player object's movieControllerlD 
properly. The Revolution documentation states unequivocally 
that “the movieControllerlD pro|x:rty is read-only and cannot Ix! 
set”. However, I'm told that this is in fact not tate and that we 
C€in assign a value to that pnjperty. Because I learned about this 
fairly late in the [:jrtKe.ss of writing this article, [11 have to leave 
the implementation of this feature as an exercise for tlie reatier. 
In the meantime, RunRevVeez will simply display a dialog lx)K, 
shown in Figure 2, when die user selects the New menu item. 


N«w is not supported by RunRevVeez. 

Figure 2: The Nmv imrning 


Closing a Movie Window 

When the user dicks the close* button of a stack, Revolution 
does nt)t immediately close the stack. Instead, it sends a 
closeStackRequest messiige to the airrent card on ttrai stack. If 
the CloseStackRequest message handler passes that mc^is;ige 
further along the message path, the stack will adually lx* closcxi; 
otherwise, the stack remains open. Ibis mecltanism gives us a 
chance io prompt ihe user to save or discard changes to the 
movie in a window, or to cancel tlie dose operation altogether. 

We also want to make use of tliis mechanism when the usc*r 
selecis the CItxse menu item in the Hie menu. Accordingly, well 
have the menuPick handler for tliat item simply send a 
CloseStackRequest message to tlie hontmost movie window. 
Listing 2 shows onr t'ode that handles the Close menu item. 

Listing 2: Maiidling the Close menu item 

munuPkk 

"Clos^" 

put first line of the openStack^ into thcTopStack 
If exists(player "KoviePlayer" of stack tlteTopStack) then 

FPnrt rlofspStarkHcquPiit to st^tek ilreTopStack 
end if 
break 

So we need to :Kld a closeStackRequest handler to the script 
associated with a movie window. Thi.s handler needs to check 
the movieChanged property of the movie window u> see if the 
movie has lyeen edited since il was last opened or saved. If it has 
l>een, we want to ask die user to .save those changes, di.scard 


them, or cancel the close openirion. We can do that with this 
lengthy line of stjipt: 

answer warnini^ "Do you want to save the changes \ 

you Made to the docuMent " h quote & the title of me \ 

& quote & \ 

with "Don't Save" or "Cancel" or "Save" \ 
titled "Save changes before " i theAction \ 
as sheet 

Tliis Ime displays tlie sheet shown in Figure 3^ 


, <^.0 Q Sjmp jt M wr t 

Do mini to tav« xht nui^ to tttt doeurtitrtr 'S4n^l4 MoviC? 


{" Pen't Sw* ^ f Cuxc%i } ^ 


i 

QukkTuiTC 






Figure 3 : fhe \Saa' changes'*sheet 

A couple of coinmenls are in order here. First, notice that 
we use the special keyword quote to emlied a [lair of quotation 
marks in the string displayed ;is the message in the sheet. Als^i, 
we use the “as sheet” tjualifior to have the dialog box drop down 
from the movie window as a sheet On operating systems other 
than Mac OS X, this qualifier is ignored and the warning is 
displayed as a sLandanl modal dialog box. In that case, the 
dialog Ixix will have the stxrdfied title, which is either "Save 
changes Ix^fore closing” or ^Save changes liefore quitting”. We 
kxik at tile custom proptmy isQuitting of the mainstack to 
determine which action is afifiroprialc: 

If tht» latluittlng of stack "RunRevVeoz" is true then 
put "quitting" into theAction 
else 

put "closing" into theAction 
end If 

(Well see how that [iroperty is set in a little while.) 

1he user must click one of the three buttons in the sheet 
(or dialog box) to dismiss it; when that happens, control 
returns to our CloseStackRequest liaiidler and the it variable is 
set to the text of the selected button. If the user selects “Don't 
Save”, we can simply pass the closeStackRequest message 
along the message path, thereby allowing the window io [>e 
closed. If the user selects “Save”, we call the saveAs function, 
which is defined in our external code module. (See the 
following two sections for more on saving edited movies.) 
Finally, If the user selects "Cancer, we w'ant to set the 
main.stack's isQuitting property to false so that RunRevVeez 
does not quiu (If we weren't already quitting, this is 
harmless.) Also, we want to execute the “exit to lop” control 
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statement to jump out of the closeStackRequest message 
handler and all other pemiing handlers. As well see in more 
detail stKin, this will halt a shutDownRequest Imndler that 
might l>e executing. 

Listing 5 shows our complete closeStackRequest 
message handler. 

Listing 5: Handling a request to close a wuidow 

dostrSiackKcqucsi 

on closestackRetjuest 

If the rngvieChatiged of this stack is true then 

- Oguit; oul ^htibcr wc arc quilling or closing 

if the isQultting of stack "RunRevVeez" la true then 
put "quitting" into theAction 
else 

put "closing* into theAction 
end if 

- ask Ihc user to save or discanl chatq^s, or lo ctticd ihc clixsc (ipcmtkm 
anaver warning “Do you want to save the changes \ 

you made to the document " & quote ft the title of me \ 

& quote ft \ 

with "Don*t Save" or "Cancel" or "Save" \ 
titled "Save changes before " & theAction \ 
as sheet 

- the kiiioii chosen by ilu- user is now in the "it" v^riul^*: handle the three caMrs 

- Caned: 

if it is "Cancel" then 

set the isQultting of stack "RunRevVeex* to false 
exit to top 
end if 

- Save: save Ihe changes and dose window 
If it is "Save" then 

put the novieConttoilerID of player "MoviePlayer" \ 
of this stack into me 
get saveAatmc) 
end if 

“ Don’t Save: loss the changes and dose window 

- (no actual code needed licrc) 

end if 

- tf we get tt) here, we want to ck?sc the window 
closa me 

end closeStackMcquest 


In theory (at least as 1 understand iij, wc- sliaukl use the 
t(3tnnian<i "pass closeStackRequest" instead of “close me" near 
the end of this handler, to pass (he mes.s;ige along the nies,sage 
chain. But 1 couldnl gel things working correctly if 1 did that, Ai 
any rate, this handler appears to do the right thing. 

Saving a Changed Movie 

Once the user has edited a movie, he or she is likely to 
want to save those changes. Unfortunately, the current version 
of Revolution (version 2.1) makes it impcxssible for us lo stive an 
edited movie into the tile the movie was o(x*ned from. Tliat's 
because, when the Revolution runtime engine calls 
OpenMovieFile to oj>en a movie file, it passes the value fsRdPerm 
as the desired file permission. Tliat is, Re%'olution always o[X!ns 
movie Hies with read-only permis.sian. So, even thotrgh 
RimRevVeez is able to actually edit a movie, it can't save the 
edited movie back into its original file. 


The engineers ut Runtime Rcvt>lution are aware of this 
limitation and have indicated to me that version 2Jd will Ixr 
able to open movie files with read/wfite permission. In addition, 
Revolutttm would need to prtsvide acces,sor methcxls that return 
a movie's file reference numIxT (which QuickTitiic returns to 
OpenMovieFile) and its resource ID (which QuickTime returns to 
NewMovieFromRIe), since we would need both those values 
when we call UpdateMovieResource, Ikcausc version 2.1.1 is not 
yet available, 1 cannot verily that it provides the capabilities we 
need lo save an edited movie into its tiriginal file. As a result, 
KunRevVeez simfily displays a warning when the user selects the 
Save menu item. It execLjre,s this line of script to do so: 

answer warning "Save is not supported by RunRevVee^. Use \ 

Save As" 

Figure 4 shows the resulting warning. 





Save is not supported by RonRevVeez. Use Save As.... 


Figure 4: Tk}e Sm>e warning 


Saving a Movie into a New File 

'I’he lie.st we cm do riglit now, thejeforc, is allow the user 
to save an edited movie into a new file — that Is, implement the 
“Save As...” menu item. Our menu handler for the “Save As..." 
item begins as usual by finding the frooimost wiiidt)w (that is, 
stack) and ensuring that it contains a player object. Then it calls 
the custom function saveAs: 

put the movieCoutrollerID of player "MoviePlayer" \ 
of stack theTopStack Into wc 

get saveAs(me) 


Hie code \hr the saveAs hmetion is contained in our 
QuickTime external; Listing 4 shows the conesponding externa! 
axle, XCMD_SaveAs. 'Ilie centnil core of this function is lH)mowed 
w'hoiesiile from our existing C-tiinguage sample code application 
QTShell, as are ihe uiiliiy fund Ions QTFmme^PutFile and 
QTUtits_ConvertCToPascalString that are cillcxl by XCMD_SaveAs. 


listing 4: Saving a [iiovic in a new file _ 

XC;MD_S;ivtAs 

^define kSavePrampt "Save Movie as:" 

#defiiie kSaveiiJeNaine "untitled.mov" 

void XCHD^SaveAs (char •arg&|J, Int nargfi. 

char "retstring,. Bool "pass, Bool * error) 

I 


HovieControiler tie * HUTdii 
Movie movie * NULL; 
char *0011 IcnanTO = NULL; 

OSErr result “ iiserCanceledErr: 
char *retstr = NULL: 
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‘pass = false; 

“error = false; 
if (nargs = 1) I 

me “ (HovieCoatroner^atol targs [Oj); 
if {me 1" NUtX) i 

movie * HCGotHovie(iiic); 
if (movie f= NUUL) ( 

FSSpec mfile; 

Boolean IsSeiected = faise: 

Boolean isReplacing » false; 

StringPtr prompt ^ 

QTUt 11 s_ConvertCToPascalSt r 1 ng(kSaveProtapt); 
StrtngPtr nieNaKic ^ 

QTU1118__Cortv e r I CTo P a s c a 1S t ring (kS a vet* i 1 eName); 

QTFrame_FvjtFile (prompt. fiieWame, femfilet 

^isSelected, ^isReplaelng); 

free(prompt); 
free(f ilr'Namo) ; 

// savr rhr m<nic In ihr solrcu'd kH'aticiit 
If (isSelected) ( 

Hovie newKovie NULL; 

short refUam - -1: 

FSRef fsRef: 

// deittt ocisting file of thai tiaita.* 
if (IflReplacing) I 

result - DoletcMovieFileCAmfile); 

If (result i” noErr) 
goto ball; 


newMovie = FlattenlfovleBata(rnovie» 
flsttenAddMovieToDataFork | 
f1 attenForceMtivieResourceReforcMovionsta. 
Sitnf i To* 

F0U[1_CI1 j\JL€ 01>E {^'IVOU^) * 

SitSyatemScript. 

createMovieFlIeDeleteCurFile I 
cteat eMovieFileDontCreateResFlle); 
result - GeiHoviesErrorO; 
if {(newHovie = NULL) || (result 1“ rtoFrr)) 
goto ball: 

// FbtttTiMovk'Jlaui crtaic^ a new tmivic file and nctumN die mmic to us: 
// ^cc wc want to ki KcvohiUon oj>cfi the new file, we’U dump ihc 
// movie returned by J-lailenMoweDaia 
DisposeHovle(nevMovie); 

// also, cm MaeOS, FtittenM<Jvienata "always" creates a resoiiree fork; 

// delete the resource fork now..,. 

#if TARCKT_OS_HAC 

result = FSpOpenHF(irmflle* fsRdWrPerm. ^refNuni:); 
if (reault “ noErr) t 
SetE«]F(refNuiii. OL); 

FSClose(refNum); 

I 

#endif 

// get the hill pathname ol" the new file (to pass hark lo caller) 
result ” FSpMakeFSRof(^rm^ll^^, SifeReD; 
if (result “ iioErr) [ 

retstr = aiullocdtNaxFBthSjlze); 
result “ FSRefHakePath(fiifsRef* retstr. 

kHaxParhSlae); 

if (result -* noErr) i 
‘retstrlng “ retstr; 
return: 

I 

1 

1 

I 

I 

I 

bail; 

retstr ^ callocd* 2); 
if (rerstr I* NULL) 

reLatr[0] = (result = noErr) ? U*; 


*retatr±ng = retstr; 


The typical Wiuvior of the ""Save As,.." menu item Ls to 
create (or overwrite) the target movie file and then to oix^n the 
movie in tliat file in tlie existing mcwic window. Iliat means that 
we need to get RuiiRevVeeic to c>[x.m that new (or overwritten) 
file and load its movie into the movie window. Tt> do this, we 
need to know the full pathname of that file, tf you look carefully, 
youll see that XCMD^SaveAs calls FSpMakeFSRef and 
FSRefMakePath to convert the file system s[X"Ci(kation of ilie 
target file into a full pathname, and that this pathname is 
returned (in relstring) lo ihe caller. In oiher words, if the Gill to 
saveAs completes successfully, the huUt-in varial>lc it will contain 
the full pathname of the new (or overwTitTen) file; if that call fails 
for any reas^m, then it will lx the empty siring or set to "1", 

If the call to saveAs succeeds, we need lu o|K"n the movie 
in the target file, as shown in Listing 5^ 

Listing 5: Loading the target movie into a movie window 

menuPick 

^ the base rutmr the file 

4iet the I tcniDc*! Imiter to 

put the last \iem of it into ncwSiackNaitu 

uet the filenutto of player "MovleFlayEt" \ 
of stack theTopStack to It 
set the title of stack theTopStack to nevStackNanie 



Icons to go! 
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set the movieChanged of Bt£ick thoTopStack to false 
get windowSetModifladfwindowlD of stack tbeTopStack, D) 

Wt!Ve .seen much of code before, since we needed to 
perform these operations w^hen we opened a movie fiJe into a 
new window. Notice that we reset the movieChanged property to 
false and call windowSetModifled to clear the window 
modification state. 

Quitting the Application 

As yon kmow, on Mac OS X the Quit menu item is contained 
in the Application menu, as showm in Figure 5^ 


- check fbr"dirty'’ movie windows 

repeat for each line theStack in the opeoStacks 

if exists (player "MoviePlayer'' of stack theSlack) then 

- ask die niuvde window to dose 

send closeStackRequest to stack theStack 
else 

- if it's not A movie window, jnsi dtJse it 
close stack theStack 

end if 
end repeat 

pass shutDownRequest 
end shutDownRequest 


^iinRevVeez 


File Edit Movie Help 


About RunRevVeez 
Preferences. 


Services 

> 

Hide RunRevVeez 

sen 

Hide Others X36H 

Show Alt 


Quit RunRevVeez 

nQ 
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Fignre 3: Ihv AppUcatkm memi 


ApPUtAIltKN DiSTRlBUllON 

Let’s finish up by considering how to link our external code 
module — which contains virtually all of our QuickTime- 
specific code '— lo our a[>[)lica!ion RunRevVeez. During 
application development, we can do this by setting the External 
References property of the mainsrack to the bundle built by 
Project Builder. Recall that ProjccL Builder builds a module 
called QTExternaLbundle, I found it most useful to copy that 
bundle into the folder containing the Revolution IDE. Then ! 
added the full pathname of that bundle to the list of external 
references, as shemn in Figure 6. The easiest way to set diis 
external reference is to click on the little folder icon and then 
navigate to the de.sired file. 


Ihis menu is supplied by the operating system, so we cannot 
attach a menuPfek script to it. Instead, w hen the user selects the 
Quit menu item, the operating system sends an Apple eveni to 
our application. Since w'e have not installed any Apple event 
handlei's, the Revolution runtime engine handles that event and 
issues a shutDownRequest message to our api^lication. ho we can 
handle the Quit menu item either by in.stalling an Apple event 
handler ar a shutDownRequest handler. To lacilitaie moving 
RunRevVeez to Windows operating sy,stenis, let’s use a 
ShutDownRequest handler. 

Well begin our shutDownRequest liatidier iiy setting a 
custom pi-oj’jeriy of the mainsrack, IsQuitting: 

set the isQuiiting of me lo iriie 

We ve Lilready seen where we need to insfiecr this piopeny, in 
the closeStackRequest handler of the movie window (Listing 3). 

Tile remainder of oui shutDownRequest handler sinij’jly 
loops through all open movie window's (using the repeat control 
smictiire) and sends the cioseS tack Request message to tliem. If 
we encoLiniLT a window tliat isn’t a movie window, we simply 
close it. Revolution applications will quit automaticaliy once the 
la.st open window is ckxsed. Listing 6 shows our com[)leie 
ShutDownRequest handler 

Listing 6: Handling the Quit menu item 

shut Dow nRrqiK'.si 

on shutDowtiRequest 

set the isQuitting of me to true 


O, 


mck "RunftfevVfeeait IP t<lg3 


tJiwrnal ftefercfices 




© 


File Path — - 

/Development Tooli/Revolution 2.1/QTExiern;!tLbundlc 


Figure 6: The exfemni references 
during t^pplianion deteiopmeyif 

'I’hereafrer, whenever RunRcvVccz is executed (either as a 
siaiidalone application or in the Revolution IDE itself), the 
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specified bundle will be used to resolve the external references 
in RunRevVeez. 

Obviously, however, this Ls not satisfactory as a final 
distribution method. It would he far belter to package the 
external and the application into a single file that can be 
installed wherever tlie user wishes, copied fn>m maefiine to 
machine, and so forth. Once again, we want to set the 
External References property of the matnstack, l:^ut this time 
lo a path relative u> the compiled applieaiion. The easie.si way 
to do that is using the message window (or message box). The 
message window is a window that allows us to execute one 
or more lines of script without having to create a me.ssage 
handler or attacii the handler to any object* Figure 7 shows 
the Revolution message window, with the appropriate 
command typed into it. 

O _ _ ___ 

... ' 

m the cKtiErrtiJt *1 «jdi TtunRevViMa'(fl /iuiaE^S/OTC^tcf naLhU'niltvi 


Q _Stack "RtinRcvVeez"* ID 10Z3 

Eictt rnal Rcfrrcnees i f ] 




© 


figure 7: '/be menage mndow 

[f we inspect the External References property of the 
mainstack once again, well see the desired relative path 

( Figure 8). 


figure S: We exlemai references for applieaiion distribiiiion 

All tJiat remains ts to copy the external bundle into tlie 
application bundle. Once we’ve got RunRevVeez working as 
desired and we’ve reset rhe External References property as 
just indicated, option-dick the compiled application in the 
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Finder and dicxm' '‘Show Package Contents", as shown in 

Figure 9- 



figure .9/ conkKictmil meiui for RunRerVeez 

Finally, copy ilie QTExternal,bundle file imo die MacOS folder 
thaFs inside the Contents folder of the window that opens up. 
We're done. 

CONCXIISION 

Let’s rake stock of what weVe learned ahout Revolution and 
QuickTime in these three articles. We set ourselves a very 
S[>ecifie goal: duplicate the functionality of our existing Girbon 
appliaition Q'i'^hell using Revolution, That meant; create an 
applicalion capahic of (jpening arhiiraiy QuickTime movie files 
in windows on the screen, support the standard movie editing 
o^x^rations, and allow^ the user to s;ive any edited movies as 
desired. Thai also meant: have our applicaikm look and behave 
like a standard double-clickable application (using native 
contiols and other widgets j>rovided by rbe operating system), 
sup[>oit an Abtml box, and iiri|)lenienl the typical menus and 
menu items for movie window^s and documents. 

Revolution was able to provide iTiost of what we were 
looking for, especially since we can lake advamage of its ability 
to call external ctjtle iiKidules. For instance, Revolution dfxs not 
provide built-in support for movie editing, but it was easy 
enough for us to add that ability by defining a lew routines in 
an external module. As I said in an earlier aiiide, writing and 
deploying an external module is so easy that 1 can’t really 
imagine any serious deveksper using Revolution not warning to 
employ tliem us a matter t^f course. In an external, we have 
access to virtually the entire set of Quicklime APIs, wliich 
can bring into play as needed. 

Well, almost. There are a few^ limitations to using QuickTime 
APIs within Revolution applications that are worth highlighting. 
We saw earlier in this article that the Revolntion nintime engine 


opens movie files with read-only pemiission. This means that we 
cannot save an edited movie into the file it was originally opened 
from. As we saw, however, this does not [iieaii diat we cannot 
usefully edit movies using RunRevVeez; rather, we simply have to 
educate the user to save the edited movie info a new file. The 
staff at Runtime Revolution Jias indicated tliat a fix for tins issue 
is in the works, sf) happily (by the time you read this) our ‘'Save 
As...” workaround may no longer be necessary. 

A more significant limitation is that die Revolution runtime 
engine installs a movie coniroller action filler procedure. I'm 
guessing that it cloe.s this to .support the messages that can l>e 
sent to a player object when various events concerning the 
QuickTime movie occur. For example, when the user changes 
the movie's current time (perhaps by clicking in the time line 
area of the controller bar, {}r by dragging the tliumb), a 
currentTImeChanged mefcsage Ls sent to the player ol^ject. 
Similarly, for a Quicklime VR movie, the Revolutiem nmiimc 
engine installs an intercept pifKxtlure so that It can issue 
hotSpotClicked messages at tlie uppropriale time. 

The trouble (as we learned in an earlier article on 
RHALbasic) is that this effectively prevents our external code 
motiule from installing a movie controller action filter prexedure 
(or QuickTime VK intercept procedure) of its own. I'his then 
limits our ability to take advantage of a large number of 
capabiliiies dial rely on an applicaiion processing messages in a 
movie conrtolier action filter procedure. (WeVe seen very many 
examples of this in earlier articles.) 

Let's lx* very dear ahout this, however: RevoluLkm isnl doing 
any filing wrong by installing and using these callback proc:edures. 
Rather, it’s providing functionality to its users in exaedy die way it 
should, 'I'he problem arises bec ause Apple has a.s yet provided no 
means of chaining movie conti'oller action filter procedures or 
QuickTime VR intercept procedures. One way out of this 
quandary would Ix^ for Apple to do exanly ihai: provide a way 
for multi pie fillcT procedures to l>e called l)y a single movie 
controller. It might also lx? possible hr Revolution to supjxirr an 
Vx|X?it mcxle” thai allowed an applit'aiion to selectively turn off 
the installation of these procedures. That would allow an extern a I 
module Xo take full advantage of these various callback 
procedures withcxit stepping on Revolution’s toes. 

So let’s wrap thing up: RunRevVeez now looks and Ixdiaves 
exactly as it should, with only minor exceptions. It can open and 
display QuickTime movies, alkw the .standard editing opcniiions 
on tho.se movies, and save the edited movies into new files. It 
gives the user an op]:>ortuniry to save or discard edited movies 
when a window' is alxjul to close or wlien the applicaiion is 
alx)iit to quit. And all of thi.s was a<’hieved with a couple dozen 
lines of script and an ea,sy-ttH:onstriia external code mcxltile. 

Crhdits 

Thanks are due once again to Tuviah Snyder at Runtime 
Revolution Ltd., who was especially helpful this time in figuring 
out seveml issues concerning the packaging of our QuickTime 
external module. 
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By Kemn Hememmy, Titillating Entertainer 

Panther Roars, Database Meows 


Panther worth your time? Databases 
besides Filemaker? Pfjfjlll. 

''Wiial\s new in Paul her?" you j>hout with mindless 
adulation, anxit)us saliva and dmtd waiting to soil the pages of 
your newest iVlaclech. Bad new^s, bub: absolutely nothing: 
nothing lo wriic about, nothing to justify your upgrading, 
nothing worth your time, effort, or worrisome heart palpitations. 
1 was hoping 1 could pound out a peck of pickled pages on 
paiheiic Panther proselytizing, but no, Apple has spurned my 
deadly Shaolin technique. 

1 am, of course, talking specifically about web senang. 

MK. PlSliR, 1 ThLNK YoLI SllOLIlD COMli Uk tll-RE 

.Sure, a lot of other incredible drool-worthy stuff has 
happened in the latest OS: Fxpirsc, word completion in 
certain applications (via Option-Escape or F5), FileVaull for 
the paranoids, gcc 3.3 and distributed building, a finished 
version of XI1, Xcode, blah, blah, blah. But web serving? 
Nothing, nadda, zilch. Happily, this is ntu really a negative— 
it’s hard to improve on stuiieihing that was nearly perfect in 
the first place (f>f course, this all depends on your needs, 
desires, and expectatitms). 

Which isn't to say there's nothing new with the Ai>ache web 
sercer and its related technology.., just nothing monumental, 
merely incremental, ornamental, and siipplementaf I’d have 
loved Xo .see Apache 2.0 and MySQL "i.O, hut let's cover the 
relevant changes we got instead. Note that I'll only cover areas 
we’ve touched upon in the previous columns: explaining the 
differences Ixrtween features we've yet to use isn't veiy^ 
productive. When the lime comes, if there are crucial differences 
between Jaguar and Panther, FI I address them. 

• Apache is now version 1.3.28; the latest avaihible for jaguar 
was 1.3.27. 1,3.28 is mostly a security and bugfix release so, 
although welcome, there's nothing to really get excited 


about. If you’re interested in the specifics and Lcchnicalities, 
you can read the sordid details at 
http://vvww,apactie.org/dist/httpd/CHANGES_1,3 (wJiich also li,sts 

mtsdifications for the just-relea.sed, as of this writing, 1.3.29). 

* 'Ibe output of httpd -V Cwiiich shows what Apache lias Ixen 
compiled with) includes a new entry; -D 
DYNAMIC_MODULE_LIMtT=64. This is a standard Apache 
compile-time setting, and controls how many mcKlules c’an lx 
dynamically loaded (fairly obvious, eh?). "64” is the standard 
Apache dcfatili; its explicit definition here is unneces,sary (l>Lit 
there's no harm in doing so). More info at 
http://httpd.apache.org/dev/apidoc/apidoc_DYNAMIC_MODULE_LIMlT.htmI. 

• Our included PUP is now version d.3.2 (as grep PHP 
/var/log/httpd/error_log confirms). Even though 4.3,4 or higher 
will probably be available by the lime you read this, a 
number erf good security, performance, and language 
enhancements were made from 4.1.2 (the latest jaguar 
version) onward. Most notably, PEAK (the "PHP Extension 
and Application Reposirory") is now part of PHP by default, 
althougii it seems io be broken in 10.3—^see "Homework 
Malignments” below for analysis. 

The PHP conrigLiration lias been improved in 
/etc/httpd.conf. Under Apache 1.3-27, we had the AddModute 
and LoadModule line.s, as well as AddType’s for .php and .phps 
(sec last month's Unlanglin^ the Web). We’ve got the same 
thing in 1.3.28, hut they’ve been slightly improved (Listing 
1). First, the MIME types are more rightly defined—theyT! 
only come into play when the PHP module is loaded 
UfModule is a simple conditionah,. //mod_php was loaded, 
then do this). I'he second improvement is the addition of 
index.php to the Directoryfndex, which allows that file to he 
served by default when someone requests a directory 
(http://disobey.com/example/). 


Kevin Heiiieiiway. ccrjiiUior ol Mac 05 AT Hacks and Spiderin^i, Hacks, is be tier known as Morbus Iff, the crcaior of disobey, com, which l>ill.H itself a.s 
"content h>r the discontented." Publisher and developer of more home cooking than you could ever imagine dike the popular open-sourced aggregator 
AmpheiiiDesk, the l>est-kepi gaming secret Gamegrenexom, the ever ignorahle Non.sense Nerw'ork, etc.), he is absolutely and [Xjsitively disgusted by the 
lack of Jolt cola wiiliin walking tiisiance. Ctmtaci liini ai morbtisOdisobeyxom. 
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• M you'd expect from a PI IP Lnstal], the <? phpinfD{); ?> we 
learned alxmi ksi issue Is different (Figure 1). Along with a 
heavier command line lliat explicitly enables a few' features, the 
configuration file (phpjni) has moved from /usr/Iib/ to /etc/, an 
aigual)[y smarter IcKation. If you've installed the rei'ammended 
phpjni (http://cvs.php,net/co,php/php-src/phpjrii-recofrm be sure 
to move if and restart Apache tstxJo apachedt restart). Even with 
the upgrade, the default Apple-siipplied PHP doesn't come close 
to tlie nuiiilx.T of features and builtHns provided by liyanage's 
version (http://wvvw, entropy ch/software/macosx/php/) or Sc'rver 
logistics’ rx)mplete ?¥\V (http://www.serverlogistic.com/php4,php). 

• Perl, which we talked about during our two CGI arlides, has 
been upgraded to 5.8d-RC3; the finai version of 5.8.1 lias 
since lx:eii released. If you already know a thing or two 
alx)ui Perl, be forewarned that any modules youVe compiled 
under Jaguar’s 5,6.0 (like XML::Parser, lITMLiParser, 
Compress::Zltb, eu'.) will need to lx? reinstalled, as the two 
different Peris are not binary compatible. Also n<rte that epan, 
similar to peii -MCPAN ^something, is also available (find out 
more with man epan). 


Listing 1: Configuring PUP under Panther 

The improved FIJP c<mfigu ration to mi Jittpd.conf 


ClfModtjle aKjd_php4*c> 

^ If plip is Uirned on, we rrspeei .plvp :ind .plips files, 
AddType applicatlon/x-httpd-php .php 
AddType application/x httpd php source .pbps 

* Since most ii'icrs wilt want Indcx.php lo work we 
« also automatically enaWc index.plip 
<lfModule iiiod_dir.e> 

Mrectorylndex index.htinl index.php 
<yifModule> 

</Ifftodule> 



Figure I: The output of PHP pbpinfof) under Pantbei‘. 


WATT, Wait, Hold Up Dog„, MySQL? 

Apache 2.0 and MySQL 4.0?'’ What’s this MySQL 
(http://WWW.mysql.COm^) thingy thing? Quite simply, it's your new 
Filemaker or 4D, only without the pretty pictures. Pronounced 
my-ess-que-ef it's one of the most popular free and open 
sourced databases, installed and readily avaNa!>!e to most web 
hosting accounts you’d normally pay monthly fees for. ILs also 
installed by default in Apple’s Mac OS X Server. Another, 
arguably stronger, database program is PostgreSQL 
(httpi//www.pgsql.com/) but, in a move sure to flirt with disaster, 
ril rudely ignore it for most of my Unlangiing the Web 
columns. Enough emails convincing me otherwise will 
certainly sway my decision. 

Since this column assumes you're not using OS X Server, 
our first step is to install MySQL. Incidentally, this is also the 
most complicated, not because it's difficult, but becau.se there 
are so many different directions in which to approach it: 

■ Compile the Source Code: TIjc geekiesi among us will lake 
MySQL’s raw scHircT? axle anti ttmiptle it fnun scratch. Tlits is ilie 
apjmracli taken by Jay GreeasfKin in liis Apple Iiitemet 
iXweloper article (http://devetoper,applacomrmtfimet/m3o^ 
Inddentally, I offered the same apjircxich in a similar welvserving 
series for 10.1: htTp://vww.matdevceiiter,com/pub/a/mac/2002 

/03/08/apache_niac_5.htrTil, Wliilc compiling lk>m s^>uK:e gives you 
ultimate tontn>l, fve yet lo see a situation tluit wasn’t adecjuauiy 
handled by using a i^re-fKiciagecI version (Ix^low). 

• Install the Official Binary: MySQL provides Mac OS X 
double-clickable installers in '^Standard”, “Max”, or “Debug” 
varieties fhttp://vvww.mvsql.com/downloads/mysqM.O.html). 
“Standard” is recommended for most, “Max” contains features 
that have yet to lx* fully tested, and “Debug” is suicidal for 
l>r(Kiuclion environments. If you’re always anxious for a 
doLibie-clickabie of the latest version in a timely fashioned, 
you can’t do Ixtter than using the officials. 

• Install Using a Package System: If you’ri' a fan of automated 
installers like Fink ( http ://fink.sourcefofge.net/) or DarwinFort.s 
Chttp://www.opendarwin.org/), there's probably a MySQL package 
waiting for you (for fink: ftnk listmysql; for r)arw!nPon.s, check 
the "databases” auegtrry). Package systems can usually 
uf)gnidc everything you’ve installed in one fell-swoop (fink 
selfupdate and fink update-all, for exampkf), and theyVe one of 
the easiest ways to unimlull a jxickagc too (sorneihing that 
most other alternatives have no ec|iiivalent). 

• Install an Unofficial Binary: 'Various user-cTeated double- 
clit'kables exist, most notably ServerLogistics' Complete 
MySQL (http://www.serverlogistiG.com/mysql.phpJ^ While not 
“official”, they're often “value-added" in srjme way, and 
Complete MySQL is no different: it conies witfi a liandy 
Sysiem Preference pane for controlling MySQL (Figure 3)^ a 
Mac OS X Staitupitem (see "Homework Malignments” for 


58 


PANniisH Roaks, Dataisask Meows 


Mac.Teui • DiciiMinyt 2003 


















































MAC OS X PANTHER 


ALL YOU NEED TO KNOW ABOUT PANTHER 




Want to know whaVs 


new in Panther? Thrn 
to the one book with 
all the answers. i 


Sams Teach Yourself 
Mac 05 X Panther 
All in One 

by Robyn Ness and 
John Ray 

ISBN: 0-672-32603-5 
$29.99 US 



Mac OS X 

I ^ 1 [ jfflovte & iDVD 
iTunes & iPhoto 
11^ ^ Inleraet 

Mac Hardware 


i^cii Yourself 

Mac OS X 
Panther 


Qnt AiV Antvwrs 




Sams Teach Yoursetf Mac OS X Panther 
All in One is designed to teach, in one 
book, the Mac user how to easily work 
with the hardware, the operating system, 
and key applications. Rather than focusing 
on a single product, the book covers 
multiple products and technologies 
together in a logical fashion. 

Topics Include: 

• Understanding the Mac OS X Panther 
interface. 

• Burning CDs and DVDs with iDVD. 

• Playing and organizing MP3s and 
digital music with iTunes. 

• Digital photography with iPhoto. 

• Editing digital video with iMovie. 


Visit www.amazon.com/samsbooks to downioad an overview 
of Panther’s new security features 


OTHER GREAT SAMS BOOKS ON PANTHER 




Mac OS X 
Panther 

um UNLkASHIiD 



iLife in a Snap 

by JInger Simon 
ISBN: 0-672-32577-2 * S19*99 

Available Dec 2003 


Mac OS X Panther in a Snap 

by Brian Tiemann 
ISBN: 0-672-32612^ • $19*99 US 

Available Dec 2003 


Mac OS X Panther 
Unieashed 

by John Ray and William Ray 
ISBN: 0672-32604-3 • $49.99 US 

Available Jan 2004 ^ 


amazon.com 


sAms 


www.sa m s pu b I ish i ng .com 



Amazon*com ts the registered trademark of Amazon*com, Inc* 



























some dps on budding your own; die official binary also ships 
with one), and various drivers for database eonneaivity with 
ODBC or JDBC. Unofficial binaries may not t?e updated as 
regularly as Uie official releases, and you am the risk of them 
not being continued at all (due to lack of interest, impetus, 
or inspiration). 

Which adventure .should you emi)ark on? As much as I like 
the thrills of a shiny new “official" release, the added treasure of 
ServerLogisUcs' unofficial binary can save you a couple of steps 
in your initial exploration. Regardless which path you choose to 
install MySQL, its continued configuration and adininislration is 
the same: you can use the command line to do everything, or 
nearly everything ihnmgh GUIs (like CocmMySQL, 
phpMyAdmin, etc.) or code (like PUP). Well cover CocoaMySQL 
(http://cocoamysql,sourceforge.net/) and PHP database ctxling 
(http://www.php.net/mysql) in our next column and, if there's time, 
possibly phpMyAdmin (http://www.phpmyadmin.net/) 

iNSTAijaNc; CoMPum* MySQL 

Complete MySQL comes with a radier vcri-K>se installation 
dcxiiment, but well cover the process quickly liere. Go alicad 
and download the latest version (4.0,15 at the time of this 
writing; the latest official release Ls 4.0.16). Kxtraci and mount, 
double-click the MySQLpkg, agree to everything, and pause for 
a second when you get to the “Select a Destination’' seamen. 

It continually surprises me how many people don't know 
atxmt the IHie > Sbotv Files command. Within any insialler built 
using Apple's package system, you can always gel a list of the 
files tliat are alx>ut to installed simply by choo.sing that menu 
item (Figure 2 shows llie file lists for Ixnh the official MySQL 
binary and Complete MySQL). Ihe list can l>e saved, printed, 
and used as a niadmap if, and when, you want to uninstall the 
package (though some creative license will need to l>e applied 
to find out where the package’s root install directory i,s, 
represented us,/), 



Figure 2: Using ‘"Show Files'^gtws}fou a roadmup for 
unimtallmg in the ftmre. 


Once tlie Installer finishes, yem should be able lo browse to 
/Library/MySQL and see a bunch of newly added files. likewise, 
you should ncxice that a MySQL Startupitem has been installed 
into /Library/Slarlupllems. Note ihul even though MyfJQL has 
successfully l^een insLilled, it lias not lx.'en automatic-ally 
suiried... there's still some initialization to do. 

Next, install the MySQL Preference Pane. Since I alone will 
be administrating MySQL, I've dragged my copy into 
/Users/morbus/Libmry/PreferencePanes/; if you’d like it acces,sil>le 
to any user on the machine, chcxise /Library/PreferencePanes/ 
instead. Once it's in place, open up your System Preferences, 
and choose the new “MySQL” item (Figure 3). 
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Figure 3: The newly installed MySQL Preference Pane. 

To finalize your installation of MySQL, you'll want to first 
“Initialize" the dalalxuse, than assign a password to the MySQL 
root user, MySQL database users iiave nothing Lo do with users 
that you've created within OS X, so don't get them confused. 
Once MySQL has Ixx^n iniiialized. “Start" the server, then “Set 
Root Password" (Figure 4). 
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f igure 4: Setting MySQVs mol password in the MySQL 
Pnfrence Pane. 

We can ensure that MySQL is running a few different 
ways: by checking the newly created logfiles Cal 
/Library/MySQL/data/compufemameJocal.err; youll need to 
authenticate as an administrative user to do so), or by 
checking the airrently running processes via the shell (ps 
auwx) or Panther's Activity Monitor (Figure 5), a much 
improved replacement for Jaguar's Process Viewer. If yc^u’ve 
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got hundreds of pr(x:essc.s, use die ‘'Fitter" input to narrow m 
on “mysql". 


A 9 0^ 

Utmr* QvH Akiu Invtct 

htcni I& V ^Kni Mpm 
IP Cr«k 

•m pAT««i 


MH 


■ CM 

fr.M 


fin 

OM 

an 

fi.n 

#.n 


4.lt « 
LTtMi 

unuf 
fiwnM 
**< W itt 
t fi] Kl 

1.14 m 
I.IKWI 


Hfi llM ' 
If TOH ' 
LKnUfi ' 

la 41 HI 

IfiJtHfi 
141 If Ml 
4141 Hi 
ir.fiHi ■ 


r a>U ^twn Hwnwir PIU Acthtliy D4iji tJiJ<p WiPnicffc 


Httal J7.0tt 
Hina. n.iia 


H 


figure 5; Verify MySQL is running with 
Panther's Actitdiy Viewer 


Homfw'ork Maij(;nments 

In our next column, we'll ltx)k into interacting with our new 
MySQL datiibase; administrative tasks from the aimmand line, 
visual interaction with GUMiased kjoLs like CocoaMySQL, 
inserting and manipulating database records with PilF, and 
fnorc\ We'll really just be scratching the surface on what's 
possible, but it1l give you enough knowledge to stan your own 
claubase pn)jetl, or feel relatively confident alx^ui installing 
someone else's. For now, students may contaa the teacher at 
morbus@dIsobey.com. 

* Who's in the attic? 

* In non-Hanther versitms of OS X, Apple manually installed 

the o[Hional PEAR, as well as a number of Ff AR-released 
modules, into /System/Librafy/PHP, In Panther, tliey 
probably opted not to do this since PEAR became a 
default PHP extension. Unfortunately, it appears that the 
PEAR installation under 10.3 ts incomplete (witness the 
“missing System.php” ccjmplaint when running 

/usr/bin/pear). Simply copying an existing System.php from 
Jaguar won't work, so you'll warn to grab the latest from 
http://cvs.php.rtet/cvs.php/php-src/pear/System.php. Save thi.s file 
to your Desktop and copy it into place with sudo cp 
’/Desktop/System.php /usr/lib/php. You .should then be able 
to am FEAR withoui a problem (list PEAR modules 
currently installed wiUi sudo pear list). 

* Every time Mac OS X Ixxtts, zillions of Lhings txcur... a fair 
portion of tills zillion Is controlled by Starty[>liems, files that 
say what should run and when. To create your own 


Startu pi terns, lake a kx)k at “Creating Systciniitarter Startup 
hem Bundles" (http://www.opensource.apple.com/projects/docijmenta 
tion/howto/html/SystemStarter_HOWTO,html) and “Sian Me Up^ 
Writing and Understanding OS X Starlupltems" 
(http://www.oreillynet.eom/pub/a/rTiac/2003/l0/21/5tartup.html). 

• If you’re interested in seeing what die MySQL FreferencePane 
actually does for you, die installation PDF provided with 
Coinpleie MySQL has the coinmand line equivalents. 
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JAVA 


hy Joe Zohkiw 

RemoteScriptRunner: Remotely execute 
scripts from any web browser 


iNTRODlJCnON 

Lately Tve been expltiring java and the many ihing-s (hai am 
he done with it. ( will atimit that tbr years I was turned nlT l)y 
Java due Uj my initial experiences with it in the Mac OS. When 
Java was first introduced on the Mac OS it was horribly slow, 
Mr)ST people first s;iw Java perfomi in the I'onn ol' an applet or 
some other l>rows<*r-based user interface - imfortunately this was 
not Java's strong suit. However, with M;k' OS X, Jaguar and 
especially Panther, Apple has made great strides in making Java 
mut^h more usable on the Mac...which caused me to give ii a 
second kK)k. 

Java is not just for user interfaces. In fact, there are .so many 
tributaries fiowing off the Java river that il^s liable to make your 
liead spin just trying to figure out w^hai Java is attually capable 
of! In fact, iPs probably safe to ,say that Java is capable t^f just 
about any tyjx* of software development you are interested in - 
all you have lo dt) is figure it out or find Si)meone who already 
has, Java can l>e used to write clients and servers, access 
databases, communicate witti mobile devices, am appliantt^s, 
write piatform-nulive ctxle, etc. in this article we ItKik at Java's 
server side - which arguaiily is a belter choice than many other 
languages (including C) when writing a ,server. 

RemcXeScriptRunner Ls a prtx>f-of<oncept Java application 
tliat runs as a daemon paK:e,ss in the background. 'Iku is, you 
won't see any icons in the Dexk while HSH is running* like mo,st 
server. Althougli Java can i>e platform independent, lliis one 
implemems the ability to exeaite AppleScripl format scripts, so 
in that regard it i,s plalfonn specific to any platff>rm that 
implements AppleScript. I iowever, this mechanism can easily lx* 
cl Ringed lo suppon other scripting architectures and is left a,s an 
exercise to the reader. 

RSK is modeled after an article written l^y David brown in 
August 1997 entitled "A Simple, Multithreaded Web Server" 
whtcli can be found on tlie Sun Java developer web site at 
http://developer. java .SLi n .com/developer/technical Artit Jes/Net w' 
orkingr^Web,server/. I reconimend you kK)k at this anicle for 
details on the server as 1 will not delve into the details of that 
here. In fact, thi,s article takes more of a "here',s what 1 learned" 


approach. The AppleScript portion of this code is intKleled on a 
code example by Scott D.W, Rankin and is available at 
fUtp;//macdevt:entencom. 

20,000 Fiiirr 

At 20,000 feet, RSR fiinctions as follows. You douhlexiick the 
cxjmpiled Java ai)pliciUion, usually in the form of a JA.K file. 
Although you won't see it in t!ie LXxrk, .suffice it to say that this starts 
the server ninning and waiting for client ctmnectioiis on jx>rt 8080, 
or any |H>n you specify. You c':m check to ,see if the server is running 
by typing ps ax 1 grep java in TerminaL If the .server is amning you 
should see a line in the result that kxiks siHiiething like 460 ?? S 
0:00.71 java Jar /Users/zobkiw/RSR/RamoteScriptRunner.jar. At tills 
fXJint tile server is active yet esscMilially itlle as it aw'airs a a>nnet:tion 
from a w^eh browser client. 

Next, a user launche.s their web brosvser and accesses the 
server as tJiey would any other 11111^ HHL. In our arse, since we 
are testing things locally, we use fittp://localhosl:8080/ but 
kx-alhost can lie 127.0.0,1 or any (Jther valid IP addiess or 
server/domain name. The .server accepts the If PIP connection, 
sees that the jet|uest is in GRT Ibmial and returns the HTML 
necessary to di.splay a form to the user. This fonii cxnitains an 
editable text area, a submit liiitfon and a button to quit the .server. 
The editable text area is u.scil lo lypc^ your AppleScript. ! 

Once an AppleScript is entered, you press ilie Submit buiion 
to POS'f the form and <lata to the server. 'Uiis rime when the 
broNvser connects to the serxxT, the sender accepts the connecti<in 
and sees that the request is in POST formal and j>arses lire data 
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in the form “ mtxst imptirliinlly^ llie Appk\Script. The server 
aitempLs uj excciiie tile script using the necessary AppleScript- 
related Java classes and returns the results as HTML to the cJieni. 



Figure I - RemoieScriptRunner in action 


In Kigiirc I we show the two ’’pages'* created by the server. 
In the first page (behind) we hive filled out the Form to include 
un AppleScript that tells the hinder to get ifie name of every itetii 
in the desktop. After sufimiLLing this script, we see tlie results in 
ihe second page (front). Note tliat the results are simply a list of 
items that happened to Ix" on my desktop at the time. 

10,000 Feet 

Zcxjining down to lO^OOO Feet, let's take a look at the 
development environment and st^urce oxle. Java development 
uxils can take you in many different directions - ail have their 
advantages and disadvantages for any partictilar project. There is 
Project Builder for pre-10.3 users, Xcode for 10.3 users and 
beyond, hc:lipse for anyone on just alxiut any platform, and then 
BBEdit and the coinmiind line. Although I've written Java ctxle 
using each of these options, for this project 1 chose BBEdit and 
the command line. When there isn't a whole lot of code to write 
I can do tilings just as easily and usually faster by U-sing these 
stand-by tools, 

So^ in this projeci 1 created tny RemoteScriptRunner.java file 
in BBEdit a,s well as the manifest file, RemoteScriptRunner.mf. 
Then I use 'lenninal to compile, run and build the JAR file. The 
command line to compile is javac -classpath /System/Ubrary/Java:. 
RemoteScriptRunner.java. The command line to run is java - 
classpath /System/Library/Java:. RemoteScriptRunner TItc 
command line to build the JAR file is jar cmf 
RemoteScriptRunner. mf RemoteScriptRunner.jar *xlass. The 
manifest file is a text file that contains two lines, as follows: 

Main- Classt HemoteScriptftunner 
Class -?atb; /Systam/libra ry/Java/ 


Because the easily accessible Brown artic:le mentioned 
earlier does such a gcxxl job at explaining die multidireaded 
nature of the serv'er, to which I made few changes, I won't go 
into the details of that here. Ihis article will primarily distruss the 
handledient meihcxJ of the Worker class dial is called after a 
connection is accepted, Ilowever, lei's quickly dtsciuss what 
leads up to the handledient methcxl Ix’ing called. 

First, the main program loads all program settings and 
c'reates a series of Worker olijects as Threads. Because it's less 
"exjxnsive" to create a few of these up-from, we do it at 
prognm initial ixaiion raiher when a connect ion Is actually 
establislied. These Worker objects are stored in a Vector and are 
available to handle connections as they are accepted. The server 
then establishes itself and loops forever, waiting for a 
connection. When a connection is e,stablished, the first Worker 
«)bjcct not already busy is pulled from the Vector and pas.sed the 
Socket that accepted the connection. At this point the Worker 
object, which was in a wail state, is notified to wake up and 
lx‘gin ti.s work, ultimately calling its handleCltent methcxl, 

In handleCUent the hrst thing ycxi want lo do is CTeatc a 
PrintWriter on the scxrkel's cnilput stream for writing and a 
BufteredReuder on the .socket’s input stream for reading. We 
also set the timeout so we don’i hang the mac hine in tfie case 
w^bere the socket is left open hut there is nothing left to read. 

// Clftate i ftuilcr anti writer 
PrintWriter pw ' new 
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PrintWrlterCclientSocket-£etOutputStreaiD(}* true); 
BuffersdReader bt * new BufferedReederCnew 

lnputStreaiDReader(tlientSocket. get Input St reati {))) i 

//We will only bkK'lc in read fbr this many nulliscconds bdbii^ wc fail with 
// java.k>jfitcmtptcdlO£Kception,ai which potni wc will abajidon ilic cormccaon 
client Socket, set SoTisieoiitC Remo teScriptRuTiiier. tineout) j 
clientSocket.setTcpNoDeiay(true): 

Depending on what l]>c purpose of your server is, you can 
very easily loop calling the readLine method of the 
BiifferetiReader repeatedly until no more data is available. I'his 
will get you (most) cvcryllting coming from the client. 

// Read ihc bulk of tJic data from ihe input by line 
String s\ 

while (((e - bc*readLine{)) t= null) (f?.length() I” 0)) 
System.out ,printliiP'> " + s); 

Wc do just this with the addition that we also look for 
specific tnlbrmation coming from the client. In Lite HTTI^ 
protocol the server receives all sorts of infomiation from the 
client when a connetaton is open, A pan of this information 
includes the type of request. Altltougli we on just as easily look 
for specific codecs and values within die URL or emlx^dded in the 
data, in this implemcniaiion we kxik for GKI' and POSIVeqiiests 
specifically and base our respf>nsc on that. We make use of the 
stansWith method of the String class for this puqxxse. If the 
siring starts wiili “CiFF I lien we respond by sending back the 
HTML containing the form. If the .string sums with ''POST' then 
we know tliat the form is Ixitig subniiticd and wc cxiraci the 
AppleSr ripi frtim it and attempt to execute it* retLirnlng its result. 

One tiling tu note alajut the readLine method u.sed alxwe is 
that in the case of a POST, readLine will not read tlie POSTcd 
form data, ‘the problem is that the form data does not end in a 
newline chanicter, so readLine essentially ignores it. Given that, 
in the case of a POST, wc have U> finish Raiding the data 
character by character using the read method of the 
UuffcR*dRcadcr. As we nrad each character, we buiki a siring 
containing all of tlie data. 

// Ru^id the- rrst t»f tin:' .ivaibhtc dau oeatc a s^tiirig of j| 

g — W« . 

while (br.readyO &5i C(ch br.readO) 1^ -I)) 
s += (char)eh I 

Once you have the siring containing ihe form data there are 
a few things to do tf> it before you use it. First we trim tlie string 
using the trim method of the String class. Next wl* decode the 
string using the decode inetluKl of tlie lIKLDecoder class, 
passing "LTI'K-H'' as the decoding scliemc. I'hcn. using the 
Slring'rokcni7er class we split the string by to extract tlie 
name and value pairs. Once we have each pair we use the 
Stringfokentzer class once again to split the suing liy This 
gives us the value of any particular field from the fonii. The 
getFonnVariaiileValue method shows the use of the 
Siringl'okenizer class, li assumes a string passed in smii as 
scrjpt=beep 3&something=this&somethingelse=that. 

// (kt 3 ft>rm v;irijjNc value from a list of variable name and dau pairs 


String getFomiVarlahleVaIue(String Viirinhlen, String nane) 
t 

// Set up our first lokcoiTef and varjabks 

SlrlngTokeulsser scl “ new StringtokeniKet{variables, "i*): 
String si = ""i 

String nl ^ nane.toLowerCaseO + 

// If ilic given name Is mn even m the variables then cjirii immediately 
if (variablea.toLowerCasnO JndescOffnl) ” 1) 

returci null; 

// Search ftic first token as n name and data pair (ic: variablt^daia) 
while (!sl.EtartsWithtnl) || al.lengthC)“^0) I 
si = stl .nextTokenO ; 

System.out.prlntlnC^fll"" i b1): 

1 

// Now tlvai we have the first token, wt‘ can split it into the mum^ ;md dan s(KCifics 
StrlngTokenUor st2 = new Slring'i'okenlzertsl. "=«}; 

String sZ = 

String nZ = name. to Lower Case 0 I 
while C£2.EtartsWithtnl) {) sZ.lengthO^) I 
eZ * st2,nextToken0; 

Syetem.out. print In ("s2“'* ^ r2) : 

I 

return b2; 

1 


At this fXHnt. by extrading tlie value of the ’’script" form 
variable we finally have tlie raw AfipleScripi to execute. We first 
create a new' NSAppleScripi object by passing in the sciipt. We 
then create an NSMutahleDin ionary object lo hold any errors 
during execution. Sending the NSAppleScrijil t>bjcci llie execute 
message causes the script to execute and return results in an 
NSAppleRvcniOescTiptor object. Ihe results in that object can 
iheu be extracted and displayed. 

NSAppleScript myScript * new NSAppleScript( bJ; 

//Thiv dktiomtr)' ttoldn iny th;iT art tntounrtJtd during script execution 

KSHutableDictionary orrors " now MSHuiableDictiotiaryO ; 

// Excoitc tile sefija! 

NSApploEvontDeiierlptor reEultE - myScript .executfiferrors): 

// tf niullipk' iltnis in Uic result we tisc tills to dLsptay rtstiltx 

int ninnberOflt&iiE “ (roBultfi mill) ? 0 ; 
resul ts. nujHberOf I tonE (); 

for (int 3 = 1; I <“ niunborOfTtoJUE: I++) I 
NSApploEvontDoscrIptor Eubboncrlptor ^ 
r^EU1ts.d 030 rIploiAiT nd ox(I); 

System, out .printlnCsubDescrlptor .stringVaiijeE)); 

I 

// If only one hem in the rcsiiU wc can use this 

if (numberOnteos.B — 0) I 

String renultStrlug “ (rnsiiliis null) ? "•* i 
rnsul tn .stringValurO ; 

System.out,pri nt 1ri( roflultSL ring) ; 

J 


Conch fsfoN 

As meniioned, R.SR is a proof-of-a:mcept for a laigcr jirojccl 
of tnine, 'fhere are many ways to improve this ctide and even 
more passilile features to add. There are also other ways to 
remotely invoke scripts, hut this was a fun projcci lo frut 
together tliat works reliably. In closing, I hope this convinces 
you U) give Java a second chanc'e — you just might like it! 
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PATCH PANEL 


By John C. Welch 

New Networking Tricks in Panther 


A quick look at some new tricks, good 
and bad, in Panther 

What’s up Dot;? 

So, once again, we have a major release of Mac OS X 

Upon m, nnd while everyone else is ooh-ing and ah-ing things 
like Expose and vertical toolbars, I, MacTech's intrepid IT 
Geek, am plumbing the networking changes to Pantlien Well, 
okay, so most of the UI stuff is not that exciting to me* Expose 
is ccmjI 1 suppose, bill J had my own methods of dealing with 
this that don't require Quart:!' Exiiemc, or yet anotlier set of 
key equivalents, (lately I’ve been having flashixicks to 
WordPerfect 5.1, and the dorky key-command templates we all 
needed with itd 

Hut Panther is a big change, and I daresay dial if youTe a 
networking type, (Ell assiinie you are, since you're reading a 
column called “Patch Paner), Panther has a lot of Muff for you. 
Now, Em not going to be able to look at everything in lliis 
column. 'Eo do so would mean die “John C. Welch" issue of 
MacTech, and while rhaEs a great ego stroke, lhere’.s a liard 
limit 10 how much of me anyone should have to take in a 
month. Instead, [11 take a look at a key element of Pant hers 
networking subsystem. 

Active Directory Integration 

This is tme of the mtisi improved aa^is of Panther, and the 
changes are a long tiruc in coming* Personal opinions of 
Microsoft not wUhsianding, it’s just sensible for Mac OS X play 
nice with Ac tive Directoiy. In this area, the bigge.st new toy is 
the Active Direciory, (AD) plugin for Directojy Sendees. This 
allow'S you to make your Mac a iiiember of an Active Directory 
domain, and he able to play aImo.sr as nicely as a Windows box. 
(J say “almost'' fjecause there’s a huge pai1 of AD that requires 
window.s, such as M^Sl, certain group policies, ACLs, etc.) This is 
ciuite different from the way you did thi,s in Jaguar, wliich used 
the LDAP connector to talk to AD, and could sometimes require 
mtxlifying the AD schema to wairk right. (To be fair, there's 


nothing wrong with using LDAP. lEs how AD does a lot of its 
work, and even with die plugin, if you want certain things stored 
in AD, you’re still going to need to modify the schema. But the 
plugin minimises some of this.) As well, enabling automatic 
Kerberos authentication at login with Jaguar was somewhat 
tricky, and not for the faint of heart. You could use ADmiiMac, 
from 'Ehursby Systems with Jaguar, and get the same level of 
integmtton as the Panther plugin enables, along with some 
extras, such as lx:iier use of Window.s shares, (no .DS_Siore 
booger files littered everywhere), and SLipport for Nl’ 4 Domains, 
(Panther’s plugin is AD only.) So, if you need to deal with NT 4 
domains, or need to integrate Jaguar with AD, ADmiiMac is a 
gieat solution, allxat not free. But tlien again, neitlier is Pandien 
In any case, with Pantlieq AD jirst got a lot easier. 

0 0 _ _ OkectoryAcens ' 

- f ^ AutktnikiniOfi ; 
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,So, as we see above in the Directory Access application, AD 
now has its own entry. Click on Active Directory, liil 
“Configure...'’ Lind you get the following screen: 
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, O 0 0 __ Dtrc^tgry Access _] 

Active Oifvctoify For^s?: ©(itoire^stxom 
Active Directory Domain: domalnname.adfofe&t.com 
Computer ID: aurora 

( Unbind.. ) 

Q Hide Advanced Optioht-- 

^ Cache ^ast user lo^n for offtine opefation 

^ Authenticate in multiple domains 

C Prefer this domain serverj m( ver.dofnam.com 

TtUa. domiin server will be used wtwn avsilabie 

c Map UID to attribute: umejueiD 

Thli attrlbi^le will b« used as the Uivqvc ID 

^ Allow administration by: COLOfEVdomaifi admms.CDLORVenterpns 

Enter proyp names separated tov commas. All 
rncmiwry ot these groups will Neve adminispaior 
privileges oa thts compcfter. 

( Cancel ) f- ' -OtC----) 

Aclk^ IHreaor}^ Plugin Conftguratian 

lo add, or hind a computer to an Active [>irec:lory domain, 
you enter in ihe fore,si name, the domain name, and the 
computer name. O' you dont have a separate domain, tlien use 
the forest name. Click on the ^'Bind..,” button, (It says 
“Unbind../ here t)ecause my laptop is already liound to a 
domain.), enter in your Mac OS X admin password, and the 
userid and password of a iiser that is al>le to add machines to an 
AL) domain, and yoif re set. Note iluir ilie userki and pa.ssword 
for the AD domain does not have to lie the logins for local users 
on that macliine. In my case, tliey’re completely different. If 
there are no errors, then your mac:hine is now a pan of an AD 
domain. There are a few options that can make your life easier 
here. “Cache last user logon for offline operations'" is very h;mdy 
for laptops, so that yon can log onto your mac:hine and gel work 
done, even wfien you’re off tlic network. If you have a large Al) 
forest, the “Authenticate in multiple domains" can make your life 
easier. "Prefer this domain server/ alk)ws you to specify what 
clomain server to authenticate Lo wlicn available. Unless you 
have a .speeifie need for this, leave it unchecked. (If you have to 
ask if you need this, the answer is probably “Map UID lo 
attribute/ allows you to map the unit|ue User ID to a specific 
AD atlribule instead of letting AD handle this. Again, if you 
aren't sure you need to do thi.s, leave tr alone. **Allow 
administration by/ leLs you give admin rigliLs to users in certain 
domain gix)ujxs. By default, the cii^niain admins and enterprise 
admins group.s are used if this option is enabled, and you oan 
add others if you like. Thi.s allows AD administnUors to liave 
administrator rights on a Mae OS X machine without having to 
create local accounts for them. 

However, if you have to set up the plugin on multi[)le 
ma<'hines, using the 111 tools can get a bit tedious. They still 


work, i:>ut automating the Directory Access application is fairly 
tedious. Luckily, you can completely set u[) the AD plugin via 
the command line, and the dscontigad application. I'he man 
page for d.sconfigad is pretty complete, and has some nice 
examples. So, to add a machine tt> a domain, the command line 
would look like the example in the man page: 

dsconflgad -a ThisComputer -u “"admlrtlstrator" -ou 
"CN=Coiiiputers. OU^Enaineerlng. DC""ads .DC*demo ,DC=com" - forest 
ads.denio^cora -donain domain.ads.apple»com 

The man page give.s clear examples of u.sing dseonfigad to 
.set up all ilie different features of ilie plugin. Including a 
conmiand line configumtion option rrcikes the pitigin much 
easier to use with other management tcK)l.s, even if your 
managemeni c'onsolc is running a different Bavor of Unix, or 
even Windows. Cross-platform automation in the 11' space is a 
goo{J thing. 

Authentication and Contacts setup 

By default, Mac OS X will search through the kjcal 
authentication domains first, then any exlemal directories, [f you 
have multiple authentication directories, or you want to force a 
specific order, then you can create cicstom authentication paths 
as in the image Ixdow: 
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MM . .. .. __ 

- - ; S gfvtcts ii<illtewtkgtlw C ^tam ) - 

Choodrt w^er« 10 ftftrch far user duih«rKUcaik>n ififormatioR. 



DireaoTV Node 

/Active Directorv/fldtaiflBt^MTn 


Dr^a rilireciorv nodes itwo fouf pfuFffirrd wder foi searc^irtv. 

Remove J ( Add.., ) 

atet It)* tock to prevent fun Her chanyes. Revert Apply 

Seiting cusiom aittbeHUcation paths 

This lulls DirL'fiory Smiutrs wheru to look, iind in wh^it 
order whun [lerfomiing aLithentiaiiion O[)emtions on a given 
mnehine. Now, there's another thing that we use directories^ lor, 
namely as disirihuted addre,SsS Ixjoks. If we take a look at the 
“Contacts'' tab in directoiy ser\'ices, we see that it IcxjksS much 
the same as the Authentication tab, and you can set up custom 
search patlis there as welh like in this image: 


, # 0 Directory Acc«4 

S*rvicqt AutNnrication Conticls ] 

OiooH wtierf to levcti tm conun bnfonmBiwi. 

Search; f Custom p>tfi 

DlfKicny N«ie 
/Nfftlnro/ranl 

fAicttvn □ir«rroryii'Bdf0i»sl.com 


Oria di^iWory nvdhEt into your preferred ofder ftor wirchl'Ofl. 
t Add., j 

(j^i Gbck th« lock 10 pfEvrni fiinhcrc)tiirvfir3i. < Rewit ’ Apply 

Setting cListoni Con tacts Jxtths 

if you cio this in Panther with Active Directory, you get one 
immediaie bonus. Ad<lres.s Book, and therefore Mail can now 
use Active Directory's Glol^al Address List, or GAI., to look for 
eimil addresses when sending mail. 

Once you have ihis set up, how s it work.^ Well, pretty darn 
well so far. 1 can log into my laptop using my AD kjgin ideniity, 
with no local account creation. My home directory is created, and 


I have access to all my Mac appliaiticjns. When 1 conned to 
shares on the Windows network that I have access to, I don't 
have to supply additional cretlenrials for them, they just work. So 
the single signori aspecLs of Active Directory work with Panther 
as well I'his is due to the other part of die AD plugin's magic, 
namely it’s Kerlx^ros suppon. When I log into my AD domain, 
since AD and Panther tx)di licavily use Kerbertxs, I automatically 
get my Kerltieros tickets. So when I attempt to use AD services, 
like access to network file shares, I don't have to re-enter my user 
infonnation. One signon does it all, thanks to Kerfieros. 

The only real problem I ran into was a momeiiDry' prolilem 
with DNS. Like a lot of network services in Mac OS X, the AD 
plugin makes heavy use of reverse DNS kx)kups to get 
information on the AD domain so that it can interoperate ' 
correctly. When 1 first tried to bind to tlie domain, 1 kept getting ^ 
reverse DNS errors. Nothing seemed to be wrongs and by the 
next morning everything was working fine, and I could bind 
with the domain, so I'm not really sure what went WTong there, j 

or what got fixed, since nothing wa.s changed on the AD side. ' 

This is a major l^enel'it to Ajiple and Mac OS X in almost 
every market they compete in. Regardless of your opinion of 
Microsoft, Active Directory is ojie of the most popular diiecroiy 
systems on the market, and wiifi good reasf>n. It's flexible, fairly 
secure, (As a product, While Windows teiids to liave a lot of 
security holes, AD has been pretty clean here,), and had 
excellent management tools. It's very dominant in tlie enierprisCj 
and is gaining ground in both tlie higlier ed and k-12 markets. 
Integniting w^ell wath AD is critical for Apple to go from a 
rcluclanLly accepted plaiibrm to an accepted alternative to 
Window's c>n the desktoji and Linux in the server rcxirn. 

1 know that in my case, the ease of setup of the plugin, and 
the liinciionality it provides is going to make my Macs a much 
[iiore accepted [lart of the network. This doesn't mean that w^e 
automatically start l>uying Macs by the tnickload, but in the 
future, if I bring up Mac OS X as a .solution to a problem, there 
won't be the automatie '‘Macs can't integrate with AD’" dismis.saL 

Hiere are still a few things that need to lie done on the 
itaegraiit>n side, such as treating a Microsoft Maintenance Giasole, 
(MMO smip-in for Mac OS X, so tlial you can properly manage 
Male's with the Windows AD admimstration tools. Giving Windows 
administrators a way to use: Group ikilicies with Macs would lie 
anotlier gexx! idea loo. Since most Mac OS X applications clon't use 
a resoLirc'e fork, it has more flexibility with installation sources liian 
Mac OS 9 did, so there is at least a theoretical pcttential for MSI 
integration that I would like to see explored a little more. However, 
for a flixt implementation, the plugin works quite well. 

CONtXOSlON 

Obviou.sly Panther contains far more networking 
improveineiiTs than just an Aaive Directory' plugin, but the 
plugin is a major new feantre that wall help Apple lie thought of 
as a much better player in the enterprise space. No matter liow 
you look at it, this can only be thought of as good for Apple and 
the Mac community. 


68 


NKW NKTWOKKING TKICKS in l-’AN’miiK 


MacTecu • Di'XriiMiJliK 2003 































Toll Free; 877 - 337-6866 
Oul'side US/Canoda; 805-494-9797 
Fax: 805-494-9798 • orders@devdepot.com 
PO Box 5200 * Westlake Villoge, CA 91359-5200 


www.fievtlepotc0in 

8f7,eE9«T<IIOW 


JIM PI y ^Asr 

upgrade Cards 

Put a G4 in your iMac, 
Beige, Blue and White, 
or other Mac. 


Yea ...it feels like that 















SOFTWARE 

MARKETING 


By Daw Wooldridge 

Driving Traffic to Your Web Site 


Online Publicity for Your Software 


l-asT monih, we expluretl how to turn your wel> site inuj u 
powerful markelin^; tool for your software. While those 
techniques will help improve your site's effetliveness, you still 
face the task of getting consumers to visit your site. Some 
clevelo]-)ers are iincSer the false impression that if they launch a 
web site, then a fltxKi of business will automatically a)nie iheir 
way. In truth, the World Wide Web gives people aax‘ss to any 
txinncHted web site, but in order for them to find your site, they 
finst need to kntw that it exists. K web site is no different than an 
isolated retail store. Sure, you may get some tx.'casional ftK>r traffic 
fn>ni people who accidentally .stumble ujxtn your storefront while 
Oil their way to another destination, but yotfre LVitainly not going 
to break any sales records lelying on dial nieiliod alone. 

Getting your site listed in the major search engines (such as 
Google and Yahoo!) is definitely a move in the riglit direUiun, 
but is that enougli? If a consumer searches for the riglit related 
keyword, your site may be listed in the results, but will it rank 
in the top ten? Will it even appear on the Rist page of search 
results? Improving your making status in the search engines is a 
science in itself (which we will examine later in this article), hut 
luckily for soffw^are developers, its not the only avenue for 
reaching [xitcnlial customers online. 

Tvrgeting Your Messagi* 

Not everytJne is going tt> be interestecl tn ytHir software. As 
weVe discusa^d in jirevious issues, your objective is to foc'us your 
marketing efforts on the seled group of people who you consider 
to be poterUial customers. This is your procluct's target market, 
i'hese people would have a ncx*d or interest in your .software 
producL. Your next task is in figure out how to reach tliis target 
market t)nline. llow do tliey find stiftware on the Web? Wlial sites 
do they visit? Once you figure out itiis imtxmani e<|uation, you'll 
have a clear picture of ht>w and where to Ixfst s|x.md your 
Internel'liased puldicily efforts anti advertising budget. 

Why is this ini|X)rtanl? Kntming your audience allows you 
to tailor your marketing message to address llieir specific neecLs* 
Plus, this Latgeied campaign enables you to speak directly to 


potential customers, so that your time and money are not wasted 
promoting your product to the wrong audienc e. 

Let’s use our finional sofiw'are product, CodeQuiver, as an 
example. QxleQuivcr is a handy Mac utility for storing and 
organizing ccxle snippets. Since the new version 1.5 would 
primarily l:>enefir software develotx^rs and w'eb designers, our 
goal should lx: to rctich as much of this target market as possible. 
With this in mind, we would want to send our CodeQuiver 1.5 
press relea.se to any site or mailing list tltat announces Mac- 
related developer news such as MacTech.com, MacNN.com, 
MaclnTouch.com, MacMinulG.com, Apple Developer Connetaion 
Nesvs (hTtp://developer.apple.com/devnews/) and the dozens of other 
pofHilar Mac* site.s. 



Hgure L A Jicttonal e-mail press release fi>r CocieQuimK with 
Hems I-11 represeniinff Ihe essential elements. 


Dave Wooklridge is the founder of Electric Butierdy (www.Gbutterfly.CDm), liic wdy design and software ctimpany re.spnnsihk for Stimulu.s. HelpLngic, 
LlniHcTp, and the pc>(Hilar deveioix^r site, RB6arage.com. 
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Anatojvtv' of an Email Press Rfij^asf 

With e-maiS being a eonvenieni delivery mccliunism, 
inosL rnagazines and web site.s prefer to receive press 
releases via e-maih Usually, they have dedicated e-mail 
addresses for collecting press releases, allliough finding them 
often re<|uircs a little online researcln If these e-mail 
addresses are not listed in the obvious places, then yoLi can 
usually find the right contact information and submission 
insirudions on either their staff pages or writers kit pages. 
MacTech's e-mail address for press release submissions is 
press_releases@mactech.com. 

Even though e-mail is often viewed as a very informal 
iiiediuoi, there are rules on how^ to properly write and format 
e-mail press relea.ses. Figure 1 represents a typical software 
press release, formaned for e-mail delivery. Since many sites 
have automated scripts that convert e-mail pre.ss releases into 
web pages or USS/XML feeds, be sure to always use Plain 
Texl with slandar<l ASCII eharaclers. Never e-mail a ]:)ress 
release to a web site in Rich Text or HTML format. Avoid 
iKsing non-standard characters such as long dashes and curly 
c|UQialion marks, which may gel ineorrecily convened into 
garlded text, making your press release look unprofe.ssionai 
(not to mention unreadable) when viewed on these news 
sites. Always ennail yourself a test copy of your press release 
so that you can proof read it for any odd character 
conversions or typos (and don't forget to run it through a 
spell checker). 

1 - E-mail Subject, The subject line is usually riie same as 
your press release's Iieadline, with the exception that the subjeci 
line is noi all capital letters (see Figure 1, Item 1). Sotiie 
newsgriJLips and mailing lists require press releases anrl 
announcements to use an indicator such as lANN], so check the 
submission instructions of each site or group betbre e-mailing 
your press release. 

2 - First Line. Tlie words "FOR IMMFDhVI H RFLEAStr in 
all capital letters should be the first line of your press release 
(see Figure 1, Item 2). 

3 - Headline, When viewed in print, the press release 
headline is usually a i>olded, larger font, so oapitali/ing the 
ieiters is often viewed as optional. Plain Text e-mails do not 
feature bold styles or variable font sizes, so headlines are 
emphasized in e-mail with all capital letters (see Figure Item 
3). Tills lieadliric is usually the title that appears on the news 
sites as a text link to your press release (see Figure 2), so take 
special care when WTiting your heatlline (and matching subjtxH 
line) to ensure that it includes your company name, product 
name, version, and the key words that describe your 
announcement. Software companies that produce shrink- 
wrapped pnxlucLs often use the word "sliips" (as in “Electric 
Butterfly Ships CodeQuiver 1.5”), instead of the default verb 
"releases” which encompasses ail software, including download- 
only shareware. 
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Figure 2, The imrciing of ymir Iieadline and Fmail Suhjea 
line are important since news sites often imt yfnirpmss 

release using that iitie phrase as the listed hylKTiirik text. 

4 - Secondary Headline. Some press releases include a 
secondary caption Ixxieath the main Iieadline that provides an 
expanded, one-sentence synopsis of the announcement (see 
Figure 1, Item 4). This line is optional, liut is strongly 
recommended for online viewing. d1ie first ten to fifteen words 
of a press release are usualfy c onsidered the most ImportanL If 
a reader does not find any filing of interest in the Itrsr paragrapli, 
then they arc typically not inclined to read the rest of the release. 
Viewing paragraphs on a computer monitor is even more 
tedious, so motivate [)eO[3lc to read tlie rest of your press release 
l>y enticing tJiem with a summarized caption. 

5 - Lead Paragraph, Hie first phrase should list your 
company s city and stale (tjr country' wlien located outside of the 
U.S.), followed by the date. Tlie formatting of fiiis phrase varies 
-- some people display the ciry in all capital letters, while others 
place the date within parentheses. This paragraph is usually 
cjuite brief, consisting of only a few sentences, but it should 
communicate the five essentkil W’s of your message: who, 
when, where, what and wiiy (see Figure 1, Item 5)^ For a 
product announcement, this pamgraph usually descriixs how 
your company is announcing the immediate availability of ytiur 
new' .software version and the related platforms it supports. 

6 - Main Texl. Tlie next one to three paragraphs after the 
lead paragraph reveal product details and key features that relate 
to this release (.see Figure 1, Item 6). Even though your 
descTiption sliould effectively promote the Lienefits of your 
softwai'e, try to avoid hyped marketing language that makes your 
announcement .sound like an infomercial. Subjeetive adjectives 
like "ultimate" do nofiiing Inn consume valuable space. With 
hundreds of new software announcements vying for attention 
every ckiy, a gfxxl press release is concise and to the j>oini, fitting 
on one ot' two printed pages (but never exceeding two). 

7 - Availability and Pricing. This paragraph should 
reiterate any specific new product features t^r updates while 
Slating exactly how and where the i>ruduct can be purchast^cl. 
This indudes your web site UliL, sales phone number (If 
applicable), pricing and any upgrade offers Liiat are available for 
existing customers (sec Figure 1, Item 7). If your softwaie 
requires any unique system requirements, yoti should also 
include that information in ihi.s paragraph. If you are sending 
your press release to a mailing list, some e-mail programs only 
display URLs as clickable hyperlinks if they are surrounded with 

and tags. For example, write the URL 

“http://www.codequiverxom” as “<http://www,codequiverxom/>” for best 
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results in e-mail viewers. Consumers can’t buy your software if 
they don’t know where to find it, and yet the accidental omission 
of the software site URL is ihe most common mistake sfiarewure 
developers make when writing press releases. 

8 - About Your Company, After the main body of your 
announcement, you shouk! include a brief paragraph aboiiE your 
company (see Figure 1, Item 8). How' long have you l)een in 
businesvs? Does your company specialize in a specihe kind of 
software? Are you well known for a pankiilar praluci? Have you 
won any awards? 'Hiis not only faimliarizes readeni and news 
editors with your company name, bui if your company has 
achieved any kind of industry recognition, it lends crc^dibility to 
your softw^are announcement. It’s inipoitant to draw attention to 
the notion of credibility because it has a powerlul effect on 
consumer pcirception of yoitr software. Claiming that you're “a 
one-fxrrson virtual company (if you don’t count the three caLs who 
cx-Tupy your home office) wlio enjoys playing Unreal Tournament 
in your spare time” is probably not cute or endearing to the 
general public. It merely diminishes your CTedibility^ making your 
company seem like a small, garage operation. 

9 - Legal Di5»claimen 'rhis line is optional, but 
rec:ommended. You are announcing ytsiir product to the world, so 
protecting yourself is never a bad idcti. Slate noi only your own 
trademarks (see Figure 1, Item hut also safegLiard youiseifby 
recognizing the ihird-parry trademarks of unaffUtated pnxlucts 
that you reference in your press relc^ase. Many Mac developers list 
Apple's trademarks in their press releases. Java devekjjxas usually 
include a reference to Sun Microsystem’s Java Trademarks. 

10 - Contact Informalton. Hoi>erully, your prews 
release wall he read not only by consumers, but also new's 
editors and softw'are reviewers, if these professionals decide 
to write an ankle or review' on your .softw'are and ref|Uire 
additional information, make it very easy for them to contact 
you. Since your press release is posted on new^s sites as w^ell, 
you should tliink cai el Lilly a]>t)Ut what intbrmalion you 
include. If you're a .shareware developer w'orking at liome, 
you may not want to list your phone numlxr (unless you 
enjoy being awakened at 5:00 AM by an unknown caller from 
Germany wuth a software question). ,Simply include your 
name and a direct e-mail address (see Figure 1, Item 10), If 
your etjinpany has a dedicated press contact, then include 
that person's job title as well. 

11 - Fnd [ndicator. Placing three pound symlxjls V # #' 
on a separate line is a .standard indicator marking thi* cmkI of 
yoLii' press release. 

hven though tlie focus of this Ltiticle is on driving tr 4 tFfic to 
your web site, dtj not ahn.se the power of press releases. Only 
send out an announcemeiil when you have scmielhing 
newsworthy to say, such as a new ]>roduct reletise, a major 
version upclare, a strategic alliance or partnership deal, etc. The 
cool new buttons you designed for yonr home page are mu 
new^sworthy. If you flood new.s editors’ inl^oxes wath frivolous 
press releiises, they will .stati treating you like the boy who cried 
wolf, ignoring eveiytiling with your company name on it. Then 


you will find getting tlieir altention t|uite difficult when you 
finally do have something imporuint to announce. 

An Online Press Room 

Put your press leleases to work on your own web site. Create 
a dedicated ‘1^fes,s Rtx>m’* or “News” page where you can list links 
to all your pre.ss releases in both ITR'IT. and PDF formats. These 
additional HTML pages (chock fiill of vital keywords) will gel 
indexed by search engines and should improve your search result 
rankings, which in turn helps media professionals and potential 
.software customers discover your web site. Providing alternative 
PDF vei^sioas allows journalists to download the press releases for 
offline reference. If you’re running Mac OS X, you can produce 
PDF versions of your pre.ss releases from literally any application 
(such as Miciosoft Word or'I’extEdit) by choosing “PiiitU and then 
clicking the “Save as PDF' button. 

Software Web Duiectories 

While some dedicated software sites like MacUpdatexom still 
acceiil e-mail press relea.ses for listing submissions, most of 
these online softM^are directories requite you to manually 
complete a web form for each new product you want listed. 
Since a large pixceniage of Mac u.scrs fretjucntly vi.sit sites like 
VersEonTrackefxom, MacUpdatexom, MacOSXApps.com, Oownload.com, 
Tuc0WS.com, Jumboxom and Apple’s Macintosh Products Guide 
(http://guide.applexom) [o find software sokiiion.s and updates, ills 
in your best interest to lake the time to list your protkict with 
each and eveiy one oi' liiese popular site.s. 

While I he infonnaikm that these web forms require is 
roughly the .same a.H what you included in your press release, 
one key difTeience is the addition of a sliort descrit>tion Held 
This field usually holds a shall phrase tlxit desaibes ytxir 
product in ten words <jr ies.s. This phra.se will accompany your 
pixxluct name and version number when line listed on the 
software directories’ home page or category pages (see Figure 
3)^ You may have a cotd prodiici, but the only way site visiiors 
will ever know this is if they dick on your firoducl listing lor 
more informafi(^n. Since most constimers <iujckly scan the.se lists 
for inlerL'sting software, your slunl de.scripfion just became the 
most impoitant element of your softw'are listing because it needs 
to entice a irser to dick on your product link, 
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Figure .i \bitrpivihtct (istuig ’s sboti, oitc-scnimce dcscrlptfon 
ou software uwh directones like VemonTrackercom and 
MacUpdaUram newels to motivate users to click the link, 

'I’hink of it as the ''single sentence sell." If you built an 
accounting program, don’t just list it with a short description of 
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“Accounting Application for Mac.” Since tlicrc arc dozens of 
acrcouniing appliculions available for the Mac j'jlatlbrm, that 
generic description simply does not do yotir prcKiittl justice. 
What makes your prcxlitd uniciue from the resL^ This phrase 
should include the keywttrds and features that will attract your 
target audience in ten words or less. For example, our fictional 
product. Cf>deyuiver, is a code snippets organizer for 
develf>pers. Why would devek>|XTS want to use it? Because it's 
designed to save iheju precious time and effotl. Using the phrase 
“Time-Saving Code Snippers Organizer for Developers*' 
accomplishes this goal in only sevcai woals. 

Search Engine Strategies 

Many of the major search engines Itave resorted to paid 
listings lo generate revenue. While paid listings wall guantntee 
[placement and drive taigeted iratfic to your well site, biidgt:i- 
conscious developers can still find stairdi engines that accept 
free siibmtssicms. Of all the major search engines, Yahoo.com and 
6oogle.com are arguably the most mipomint to your siifrwart" 
business. Other popular search engines im’kide LookSmart.com, 
Search.A0L.com, MSN.com, AltaVista.com, Ask.com (Ask Jeeves), 
Lycos.com, Excite.com, AIITheWeb.com, Aboutxom, DM0Z.org (Open 
Directory Project), etc. 

"ITie list of sites may seem a little ovenvhelming, but the 
truth LS that many of tlieni utilize the same search technfilogy 
under the hcxKl, so if youTe listed in one of iltein, t hances are 
you're listed in many of the others as well. Overture and Inktomi 


(which are owned by Yahoo!) power the search results for 
dozen.s of sites such as AltaVistaxom, AliTheWeb.com, About.coiri and 
MSN.com. Many sites sucli as Search.AOL.com also provide 
additional content from DM0Z.org (Open Directory Projea). 
Yahoo-Com and Search.A0L.com lioih utilize Google’s .search rc-sulis, 
and hundreds of affiliate .sites di.splay Gcxigles sponsored 
AdWords links (htlp://adworcls.google.com). 

'fo navigate through the confusing landscape tif sLiirch 
engine marketing, it’s be^st lo devise two strategies: one for 
purchasing paid placement and one for free submissions. While 
it might seem like a no-brainer to foc:us only on the free 
.suhiTii.s.sion.s, ncme of the .search enginc.s guarantee placement, 
and even if your free site listing is accepted, it could take weeks 
(or even months) for the listing to appear online. Paid placemeni 
not only guanintees your listing (with fast, priority prcKreSvSiiig), 
bm .some sites will not accept free sulimissions from commercial 
etitiiies {such as a softw'are company), so paid plact^meni is 
otten your only option. 

For iluxse devclo|x.‘rs witli limited marketing budgets, a 
gcKKl starting point is to submit your site 1 LRl, to as many scare It 
engines as pcxssible that ac'ccfX free submissions. There are 
several software ttx>ls available for submitting your site to 
dozens of search engines from a single form, but the major 
search sites have become very .savv^ at recognizing spam and 
automated subini.ssions and often reject those listings. Manually 
sulemitting your site to each individuiil search engine re(]uires a 
lot of time and patience, but it often yields the Ixst results and 
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fine-tiined control over selected keywords and directory 
categories. Most search engines such as Google provide links 
named “Add a URL'’ or ""Suggest a Site/ Follow iheir posted 
instnictions and see what kind of results you get in the months 
to come. If youVe nor happy with your search ranking in Google 
and other search sites, liten you ran always invest in paid 
placement campaigns. 

Yah(K)! accepts free sulimissions for nonHrommercial sites, 
hut all commcaiai sites are now re<|uired to sign up for Yahcx)! 
Express for US$299 per year. Yahoo! can still decline your site 
listing, hul your Fxpres.s siibmis.sion Is quickly evaluated within 
seven working days, A fretiuently overlooked lienefii of paid 
placement in human-compiled web directories like Yaluxj! and 
U)okSmart is that It often influences your search ranking in other 
search sites like Gcxigle, If you <io purchase paid placement on 
various search engines, make sure you read the line print. Some 
plans require you to pay per click on top of the initial service 
lee, and although iticr cost per dick is tisiiiilly very low\ it 
definitely can add up quickly. If your listing garners a lot of 
dick-lhrough,s, your “pay for play" campaign may prove to Ix" 
both successful and expensive. 

There arc coiiipaiiies ibr hire that specialize in srardi 
engine placemem and optimiz;iiion. At one titne or amriher. 
we’ve all received spam e-imils with special on'ers that 
guarantee “top ten” placemen! in hundreds of search engines for 
only US$39.95 or less per month. If ytju deckle to hire one of 
these firms, he very careful wliu you choose, 'lliere aie many 
reputable ex[)erfs who produce stellar results, but I here are even 
more sctim artists who will take your money and run. Do your 
homework and research the niilestones iheyVe achieved for 
trther clients Ixfoa* signing on the dotted line. 

Optimizing Your Site i ok Search Engi^jes 

Internet marketing gums often talk about foolproof w'eb 
page optimization solutions for improving your site's rankings 
in the search engines, but the plain truth is that there is no 
one “magic bullet" lechnic|iie that works across the board, All 
the search engines have their own unitjuc indexing and 
ranking algorithms, .so your level of success will lie in 
employing several optimization tricks in an attempt to cover 
all your buses, Optimize your wel) pages BEFORE submitting 
your URL to search engine.^. Keep in mind that hutiian- 
coiiijjiled web direcUiries like Yahoo! rely on your stibmittecl 
site description and keywords for proper category placement, 
so changing your pages wall not increase your ranking in 
those wet) direOorics, Modifying your web pages will only 
affect your mnkiiig in \Tawler" sites like Google that visit and 
index web sites. 

Searcli engines used to look for specific META lags in 
your iri'ML code iu help categorize and index your web 
pages. Over the years, many of the tiiajor search engines 
have stopped looking at META tags since so many web 
marketers have abused the letimology by inserting hundreds 
of unrelated keywords in an afiempt to trick these systems 


into granting higher search rankings. While only a handful of 
search engines stilt look at META tags, you .should still 
include them anyway since many experts believe that the 
presence of these extra keywords cun still influence your 
overall placement, 

<llJiAD> 

CTITLE>Cod€Quivfir“ Time-Saving Code Snippers Drgantzor for 
Software Developers and Web Defiigners</TTTnE> 

<META tJAME-="description" COtrrKMT'’'^CodoQulver la the time- 
saving code snippets organiitcr for softwiire developers and 
web desigTiers. 

<META WANK"’^keywords'' CON iwr”**code. snippets, syntax 
coloring* source code, Mac. progranmlng, development, 
sofIw^tre* library, organizer") 

Mile [>escTiption MITA tag aixl the Keywords META tag 
should lx>th lx placed within the I lEAl) tags of your web pages. 
An effective description is one that avoids hyped marketing 
jaigon and is usually limited to 20-30 words, no longer than 200 - 
250 characters* Don t go ovedxjard with too many keywords (try 
10 or less) and don't n.^fxat ke>words. Many search engines 
reject site submissions tliai hide hundreds of rctxaied ke>avords 
in META tags, invisible comment tags, image ALT tags, etc. 

So if META tags are not as effective as tliey once w^ere, what 
are the primary elements that search engines currently do 
analyze? Here’s a ciuick list of several site optimizaiions that 
.should help improve your status w^iili the major search engines. 

TITLE Tag, M’liis is often the phnise that is used as the 
hyperlink text wlien your site aj^pears in .search re.sulLs, so 
including the right keywords wall not only improve your 
ranking, hut alst) entice coasumers to dick on the link. 

Text PlacemeiiL Search cngities will scan die lop half of 
your W'eb pages for relevant keywoiid patterns in your text 
headlines and paragraphs. Unfortunately, lots of i n'MItable lags 
or JavaScript code that push your text paragraphs further dowm 
the page can negatively aftecl your scnirch rankings, Scitrdi 
engines cannot read text embedded in Flash or images. 

HTML HyperUilks* “Crawler*" sites like Gcxjgle index your 
site by following I flML links from your home page. Tlie more 
links that interconnect all of your w^eb page.s, the more indexed 
pages that can u])iK"ar listed in search rt'.sults. Search engines 
am not follow links embedded in I 'lasli, imagemaps or dynamic 
[ava.Script code. 

Avoid Frames* Most seat'd i engines have Lroubie ft>llc>wing 
links to frame pages. .Since the home page is usiially the main 
frame.sci page with little to no text, .search rankings w^oiild surely 
plummet wlien frames are involved. 

Moving Forward 

While there are certainly other creative avenues for drtvitig 
traffic to your web site, die methods illu.sirated in this article should 
give you a solid head start in pronMiting your softw^are [iroducts 
online. In future installrnenis of this ct>lnmn, w^ell explore other 
web traffic building techniques such as online advertising, link 
exchinges and revenue-sharing affiliate pixjgrams. 
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By Chris Kilhoum 


Pursuing the Dream 


From Dream to Reality 


The Dream 

Chiince.s if you art^ reaclin^* this you are likely 

a coder, a haaiware engineer, a sysUrtas adniinistralor, a nelwtirk 
manager or some mixfiire of all four. 

But deep inside of yon have a dream, a dream of Ix^ing an 
tMiirepreneur 

You have code, a hardware product, or a weh service you're 
working on that will rock the world and make you a mint — if 
you only knew where to start. You learned how to sling ctxlc, 
balance capacitors and [dumb networks, not read balance sheets 
or write business plans, after all! 

Maybe your desire to strike oui on your own and l>t: your 
own i^ass is a burning ilame, or maybe an ember just sparked, 
Mayl’je youVe been nurturing your idea for yeai^ and have been 
slowiy working row'ards realizing Ihe drtfam, or maylx.^ it just 
occurred to you in a flasli of hisight tills morning while in the 
shower. But you k[iow that at some point in your life you wuli 
strike out on your own. 

IVc lieen there. 

In the Spring of 1994,1 found myself w^Jiking at a job where 
my fortunes shifted from a position that 1 thought embrac^ed 
Leclinological innovation, professional advancement, and 
learning into a bleak future o\' technological stagnation and 
mind-nitmbing sameness enmeshe<l within a stark^ bureaucracy. 

Hired to f)crfonu systcitLs analysis for a multi-unit division 
at a large educational irtstitution, 1 poured tliree months of my 
life into assembling a plan to integrate seven different 
departmental inforniation systems llial included sc'ra[>s of f>aper, 
IlyperClard stacks, FileMaker chitabases, Excel spreadsheets and 
VAX terminal systems. 

The final plan incorporated elienFser\er teclmology, the use 
of Newton PDA's for data-collection, and would have cut the 
time my division's departmental managers spent poring over 
budget reconciliation printouts to nciir zero. This was cutting- 
edge stuff in the early 90's. 

After presenting plans to iny two managers, I was duly 
informed that there was no budget to actually impkanent tiic 


plan. It seetns that there were two vital bits of information they 
neglected to Lcll me during my interviews: first, there never really 
was any budget to implement a plan, hut only budget for my 
position; and second, they thought it would take anyone they 
hired at least a year or two to pull Logether a plan. In the 
meantime, diey could secure budget for implementation, 

Needle.ss to say, I was not amused. 

Angry, confused, upset, and feeling misled, 1 retreated to my 
office for the next few weeks and stewed about the situation. 
Meanwliile, this thing called the World Wide Web was starting to 
pick up steam and 1 threw a copy of MacH l1'PD on a Mac If in 
lltc back rtxan, taught myself HTML in a day and sei up a 
personal web site. 

Working on the web .server and posting ecjpiously to 
USENET cKCupicd most of my working clays as I had pretty mucli 
completed the job task I was hired to do given the budget 
sintation. It wasn't until I stumbled atTf>ss a web-enabled 
dautbasc that the liglu liulli went on in my head on how to do 
the job I was hired to do using even more cutting-edge 
technology; for free, even] 

I .spent the next few weeks coding a demonstration for my 
managers, laicling in departmental sample data, and re-wiiting the 
plan with these new web tfx>ls in mind. My presentation scheduled, 
the appointed day and hour arrived and I began my demo. 

Explaining that this was brand-new, evolving technology 
with some current feature limitations that would shortly be 
addres-sed, I walked tbem through how ottr various departments 
could use the web for data collecfion and dissemination. As I 
wrapped up the presentation I laid before them the denouement: 
it was all free and would not ret|uire any budget Silence settled 
into tlie room save for the gentle w^hining of the UVAC and 
computer tans. 

I will never Ifoigei the last five niinuies of that meeting for 
as long as I live. 

4'he managers looked ar each other, looked at me, then 
shifted in their chairs and looked at die computer sciren where 
I had done my demo, whereupon the division manager aimed 
to me and asked: 

"Where did you gel the ecjuipment to do this demonstration 
vvitli?" 


Cfiris Kill>ourn m an independent smA\ husiness, network and weh infrastructure coasultant. Chris is also the founder of digital forest, Inc., 
http://www.forest.reL which offers daiaha.He, application and wel) hosting .services in addirion to server roIcK'ation. When he's nor out running marathoas, 
you may coniact him at dirisk@forest.net. 
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Not, "Mow does this work?" or *ls it really hee?" or "1 don't 
understand it, hut it looks intriguing." 

I was puzzled and did not know how to answer die 
question. I wa.s exi>ecting all manner of questions or comments 
from deployment times to resource issues, bur this one came out 
of left field. 

Confused, I explained the computer was one of our spare 
desktops that we kept on hand in case someone's computer 
went on the fritz and needed an immediate repiaeement. 

T was then subjected to a liarangue almit the misuse and 
mi.sguided deployment of division assets and how my time could 
be heller sfienl on other lasks. 

During this managerial tirade, I had a moment of 
personal clarity, 

Namely, that it was time for me to move on and pursue a 
childhood dream of owning my own business* 

1 had greater aspirations than battling budgets and 
shorrsighted managers for the rest of my career. The pension in 
the far lulure was enough of a reward for my co-workers daily 
toil-s^ hut for me, ii wms not, 

As a network and systejns administrator, I knew' my way 
around file systems and routei-s well enough, but 1 felt lost in the 
wilderness when it came to figuring out how^ to take my idea 
and turn it Into a business that people would actually pay me 
money to do. Never mind not knowing where 1 was going to gel 
the money to start the business, nor undersiand how- to market 
my service! 

TiIL PLLfiNGli 

1 think that there are a lot of you out there today who are 
wliere 1 was almost a decade ago: sitting on a business idea, but 
needing some encouragement and direction in order to leap inlt) 
the world of the selbemployed. 

Now', almost ten years after t totik the risk to go into 
business, the eomjxiny 1 founded, digital.forest, is .still going 
strong. Living ptTK>f that even if you are more comfortable, as I 
w'as, in front of a l,cn screen, te.si bench, or patch panel than in 
front of a group of [>anlters, you can still succeed in business. 

Mac lech also thinks that lliere are a lot of you out there 
ready to t‘hase the American clream, and over the next year we 
will Ixf publishing a .series of articles wriLten by yours inily about 
how to start and am a business. 

I'll share practical advic'e about how' to stan and am a sinall 
technology liusine.ss. There are hundreds of btKiks out there 
alxiui how to write a business plan, psyche yourself up for the 
entrepreneurial challenge, where to find customers, and how to 
raise money lo gel started. 1 read <iuiLe a few of these IBooks as 
initial research l^efore I launched digital forest. 

It wasn't until years later that I learned that those books 
gave short slirifi lo the reality that few people will really read 
your busines^s plan, tliai starting a business is a lot harder than it 
appears in the movies, that tliere are customers you do not want, 
and dial raising money to gel the business off of the ground and 
keep it going can consume huge portions of your time. 


fm hoping that by sharing some of my successes and 
failures, along witli insight and advice about the nuts and bolts 
of running a busine,ss, that you can only receive from someone 
who's been there before, you will be al:)le to get a leg up in 
getting your venture off the ground^ while avoiding some of the 
pilfalls that 1 fell into. 

What Do You Think? 

Space will preclude me from covering every potential topic 
or issue that you might want Lo know about, so I would like to 
solicit your feedback and questions in shaping future columas. 
Mayf)e you have a question about patents and trademarks, or 
how to value a company for sale* Or maybe you want lo know 
how to find a good office broker, or how to evaluate an 
advertising agemy, 

Send me your (|uesiions, and Til do my best Dear Abhy 
impression and devote some S[Xice in each column to 
answering them, If there is a question that is outside of my 
scopc^ of experience, 11! use my network of colleagues, 
accountants, bankers, lawyers, etc. to find an answer for you. If 
I receive enough questions about a ceiTain topic, HI devote a 
full column to it. 

What’s Next? 

Over liie next several months we will examine: 

• Why you would want to start a business* The long hours, 
the financial risk, the glamor of denning out the company 
refrigerator; who wouldn't want lo start their own business? 

From frustration with a current job to realizing a childhcxid 
dream, everyone has a reason wliy they want to .start a 
business* Well take a doser look at Ikjw your molivatien for 
starting a busine.ss can shape how you do business and 
define success along with exploring some of the hazards of 
choosing this life altering course. 

• Business phinning. Post ,com, it is now crystal clear lo 
everyone that businesses without clear plans are doomed to 
failure (at least, 1 hope it is). Hveii though, in retrospect, my 
first business plan, (and even some subsequent ones) w^ere 
lauglialile, ihcy did provide a direction lo move in wlien 
things were unclear. 

And no, your business plan is not the cocktail nafikin you 
sketched out your idea on! 

• Banking, legal and accounting issues. I know that most of 
you would much rather be cleaning out die bit bucket, or 
taking a spin at front-line technical .support than spend your 
lime dealing with bankers, lawyers, and accountams. But, 
like regular visits to your dentist and doctor, these folks are 
vital to the health of your business, and you need to know 
how they can help you. 
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ItelitfVt' ii or noi, Vvv mcl profession;!Is in ilicsc arcus itiai 
knew more tlian I did in some teduiical areas, so set some 
of your precontef^tions aside. HI help you ferret out the 
smart ones who won't gouge you, and cover the ki.sic things 
you will need from them. 

• B(M>kkeeping and financial management. It'S all about 
money. You have to pay attention to it, or you won't liave 
any of it. 

[ust like debugging code, an oscilloscope or a packet 
analyzer, having a firm grasp on Imsiness financial metrics 
will provide you with a powerful icxil for decision-ilia king, 
and assist you in evaluaLing business performance. Well 
tour die fialance sheet, income statement, and chart of 
accounts with an eye towards the vital bits. My mantra has 
always been cash flow, cash flow, ca.sh flow, and HI 
explain why. 

• Business structures. f.LC, C-corp, sole proprietor, 
partncrsliip, LLP, S-coqi. Learn how your business simcture 
afi’eas your future growth, and how^ to select the correct one 
for your type of business. 

Organizing with tlie correct business siaicture has huge 
implications for future growth and taxes. Select the wrong 
rme, and you could l)C making an expensive mistake. 

• Sales. Arguably the mo.st diffiailt thing for a technical person 
to iearn lu>w to do efTectively. However, without selling, 
you1l lie out of business faster than cuny through a Iraby. 
Learn how to rake your expert knowledge and turn it into a 
sale.s UxiL 

• Marketing and advertising. Besides taking out a m^o-page, 
4-color spread in MacTcdi, there are other ways to promote 
your business. 

From guerilla markeiing to free and low-cost advertising, 
tliere arc a myriad of ways to let the world know that you 
are in business, and w'orthy of having your customers send 
you tlieir cash. 

• Staffing and recruiting. With the current economic climate, 
looking for .staff is an invitation to Ixr Iximbarded by 
electronic and pajx^r resutnes ;md phone calls from potential 
employees and staffing firms. 

Many businesses founder due to |xx>r stolfing elioites and 
the founder's inability to let other people do W'ork. Unless 
you're w^orking as a lone ranger, you wall need to learn how 
to hire, manage, and most imfxjrtantly, delegate. 



Long Distance 




Straight 6 se€ortd biffing imremdnts 

Excellent rates on mtrostate, intrnlata/toll calls 
and internotional calling with no term controct. 


Toll Free (800/888/877/866) service, 
same low per minute rate for incoming calls 


10 cents per minute calling card. 

Deloiled billing directly from Capsule Communications, a Covista Company. 

Quality electronic and telephone customr support. 
No monthly billing fee if you sign up for AUTOPAY billing 
option or if your bill is over $20.00 eoch month. 


(KOIL $1001^ ke B thurgei when ym bilis under S20.(V for adnm-M^ nBtaners.t 
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• Fundraising. A bhck box to most, finding the money Lo 
start and grow ihc bu.sine 5 .s can he tlie hardest nul lo crack, 
Many businesses fail because they don't have enough niciney 
at the outset to grow to profitability. Business bot^ks 
cuf>lierTiisLicaI]y call this "uader-eapitalizadoiL'’ 

Only call a potential investor on the second day of a stock 
markcl upswing. Bankers will tell you what they need from 
you in order to loan you money, you just have to ask them. 
Selling your product or service is the most reliable way to 
raise money. Friends and family want more than their money 
i^ack. riJ cover these, and other secrets of raising money to 
get off the ground and bind growth. 

• Growth and management issues. Growth can kill and has 
killed a)mpanies in the past, (Apple Computer is the 
exception, not ihe rule.) learn how^ lo manage your 
coiupany^s growtli Ijcfore it strangles your business. 

• Success and failure. So, you made millions, or leli nothing 
hut a Kjntiking fiole in the ground. Now' wliai dt) you dti witli 
the rest of youi lifei' 

Th£ FtAR OF Starting A Businbss 

1 know that some of you are sitting out tliere right now, 
thinking about taking the plunge of bectiming self-employed 
but you are been held back by the fear of taking the risk. 1 
know that 1 was panially terrified before I made my decision 
to quit my job and start digital.forest, hven though my job 
w^as terrible, it did have great benefits, and the paycheck did 
clear when I deposited it. Letting go of that safety net is an 
act of faith in yourself, but it does not require you to let go 
of your fear, 

i was afraid that 1 dkl not have what i[ would take to make 
the business a success. I was afraid of all t?f the debt 1 would 
Incur. 1 was afraid that it would rake time away from other things 
in my life that were imporiaiil to me. I was afraid that there were 
people out there wlio w'ere smaiTei’ than me, who were better- 
fimdecL who had mn a business before, and W'lio w'ould crush 
my l)Lismess. 

What I found w'as that no mailer my competitor's 
experience, stockl:>rokers have it right: past sLtecess does not 
guarantee future performance. The Hip side is also true: past 
fa I lures (iir lack of ex^xmeiice) do not guarantee future failures. 

1 found that the debt, while painful, did not kill me. 1 
found that it dkl lake me aw^ay from some impoitaril things in 
my life, I)ul openeci up new inieresls and inUtKluccd me lo 
new friends. I found that even though there w^ere people who 
were smarter, better-funded and had run a bu.siness beffrre, 
Lhc 7 were so busy running their own business, they didn't have 
time to pay attention to me (Some of ilieiiT even lielped me out 
IVc^m time to time). 

Unless you have the emotions of a rfx:k, you will find that 
fear can l>e the greatest enemy of your success. Fve met i>eople 


who seemed Lo l>e the most self-assured and successful people 
in the world and they have confided in me their fear of l:>eing 
overextended, of their competition, and of their ability to 
successful iy navigiite their business through treacherous waters. 
It just a>mes with the territury. 

You need to be aware that fear creates one of two 
responses in animals, human beings included: fight or flight. 
Fear can crush you, or it can spur you on It^ greatness. You iicx:d 
to l^elieve in yourself and your dream and if you do not, you are 
not ready to pursue the dream. 

Each lime 1 found myself in a hard spot, 1 thought track Lo 
dial moment when I realized it was time for me to slait a 
business. 'I’he fear of returning to that type of work environment 
was always greater than whai I faced. 

i'ind the toLiclistone of your dream and use that as the 
bedrock upon which to stand and face your fears. 

Disclosurl 

In the interesi ol' Rill disciosme, 1 am neither a lawyer, an 
accouniani, nor a banker; I don’t even play one on television. 
I'm just a net working/systems administrator who learned 
busines.s management skills ihe liard way, by doing. 

i’hat Ixang said, before you gt) off and make any soil of 
decision dial lias legal, lax, or financial implications, consult with 
a professional in the field. 

The Reai iit 

Fill lK)ping iliat tliese columns will help you out cm the road 
to stinting your own business or help you with your existing 
Imsiness. Kveryone .should be aware of the fact that staning a 
Inisiness is hard work and that iiio,sl Ixisinesses will fail within 
their first few years. 'Hie statistics do not lie. According to the 
Jiimall Business Administration, of small businesses fail in 
their first year and 9S% fail within five years. 

Your goal is to Ixf in the 5% of businesses that succeed. 

Staning a business is not for the faint of hean. It will be hard 
work, it will take you awiiy from other things in your life like 
family, frieiids, and hobbies, and it will require sacrifice. 

If 1 had known how hard it would be to start 
dighal.forest, 1 never would have done it. It negatively 
impacted my health, my relationships and my financial 
situation for several years. Yet now I cannot imagine not 
being involved in some son of 1 nisi ness endeavor as an 
owner or principal. For the rest of my life, I will always be 
involved in starting businesses. 

In the end, nti matter your motivation for starting the 
bu.sines.s, you do ii for yourself, just be aware that the deck is 
stacked against you and iliat you need to hold your dream close 
to your heart in order to be sutx essfiil. 

G(X)d luck! 

Next montb: Hrm the decision to starl a business uili 
change your life. 
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Revolution 2.0: the English like language designed around the way you think. 
Develop and deliver on Mac OS X, Windows and Linux ' 

{not to mention 10 other platforms). 

Take the English language,add elegant XML, more SQL databases than you care to learn, ' : ■ 

intrinsic video capture, Unicode, CGI scripting, sophisticated Reports, and build your solution faster than anyone else. 
Jaguar, Panther, XP? Revolution lets you eat platforms for breakfast. And speaking of eating, our Cookbook of examples 
you up, running, and productive NOW. You can join the Revolution for as little as $99», 

. deliver with it, love it - and still have time for vacations. 

And for a limited time, your MacTech special lets you get 1 00% of the Revolution for 15% off - 
go to special.runrev.com NOW^ Thousands of developers have already joined. 

_ j . ’ Don't let the Revolution in modern coding start without you... 
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